◇

TagsInput

6 parts

A headless tags / token input: type a value, commit it on Enter (or paste, Tab, blur, or a custom delimiter), and manage the resulting list of tags with full keyboard navigation, duplicate/max guards, and accessible labelling. Use it for free-form multi-value entry such as email recipients, keywords, skills, or filter chips. Wraps the Item, ItemText, ItemDelete, Input, and Clear parts and provides their shared context.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  TagsInputRoot,
  TagsInputItem,
  TagsInputItemText,
  TagsInputItemDelete,
  TagsInputInput,
  TagsInputClear,
} from '@robonen/primitives/forms/tags-input';

<TagsInputRoot>
  <TagsInputItem />
  <TagsInputItemText />
  <TagsInputItemDelete />
  <TagsInputInput />
  <TagsInputClear />
</TagsInputRoot>

API Reference

TagsInputRoot

Root

A headless tags / token input: type a value, commit it on Enter (or paste, Tab, blur, or a custom delimiter), and manage the resulting list of tags with full keyboard navigation, duplicate/max guards, and accessible labelling. Use it for free-form multi-value entry such as email recipients, keywords, skills, or filter chips. Wraps the `Item`, `ItemText`, `ItemDelete`, `Input`, and `Clear` parts and provides their shared context.

Prop	Type	Default	Description
`defaultValue`?	`U[]`	`[]`	Uncontrolled initial value.
`addOnPaste`?	`boolean`	—	Add on paste (respects `delimiter`).
`addOnTab`?	`boolean`	—	Add on Tab.
`addOnBlur`?	`boolean`	—	Add on blur.
`duplicate`?	`boolean`	—	Allow duplicate tags.
`disabled`?	`boolean`	—	Disable the whole component.
`delimiter`?	`string \| RegExp`	`','`	Character or regex that splits/commits input.
`dir`?	`'ltr' \| 'rtl'`	—	Writing direction. Falls back to `ConfigProvider` when omitted.
`max`?	`number`	`0`	Maximum number of tags. `0` disables the cap.
`convertValue`?	`(raw: string) => U`	—	Map a raw input string to a tag. Required for non-string tag values.
`displayValue`?	`(value: U) => string`	`String(v)`	Render a tag value as text.
`name`?	`string`	—	Native input name. When set, a visually-hidden mirror input bubbles the tag list into the owning `<form>` for native submission and validation.
`required`?	`boolean`	—	Mark the field as required for native form validation.
`id`?	`string`	—	Id forwarded onto the inner `<TagsInputInput>` for `label[for]`/aria wiring.
`modelValue`?	`T[] \| null \| undefined`	—	Two-way bound value (`v-model`).

Emits

Event	Payload
`update:modelValue`	`[value: T[] \| null \| undefined]`

TagsInputItem

Item

A single tag in the strip. Provides item context for its `ItemText` and `ItemDelete` children and reflects selected/disabled state via data attributes.

Prop	Type	Default	Description
`value`	`U`	—	The value associated with this tag.
`disabled`?	`boolean`	—	Disable this specific tag.

TagsInputItemText

ItemText

The visible label for a tag. Renders the item's display value and exposes an id that the surrounding `Item` and `ItemDelete` use for `aria-labelledby`.

No props or events — renders its element and forwards attributes.

TagsInputItemDelete

ItemDelete

A button that removes its parent tag from the list when clicked. Render it inside `TagsInputItem`; it is labelled by the sibling `ItemText`.

No props or events — renders its element and forwards attributes.

TagsInputInput

Input

The text field where new tags are typed. Commits the current value on Enter, on the configured delimiter, and (when enabled) on paste, Tab, or blur, and forwards Backspace/arrow keys to the root for navigating the tag strip.

Prop	Type	Default	Description
`placeholder`?	`string`	—	Placeholder text.
`autoFocus`?	`boolean`	—	Focus on mount.
`maxLength`?	`number`	—	Max input length.

TagsInputClear

Clear

A button that removes every tag at once. No-op when the list is already empty or the component is disabled.

No props or events — renders its element and forwards attributes.