On this page
TagInput
Headless, unstyled text input that turns entries into a list of string tags. Enter, a delimiter, paste or blur adds the trimmed text; blanks and duplicates are dropped. Backspace or the reading-start arrow at the start of the input moves into the tags. TagInput.useTagInput() reads the tags from inside the root.
Use for
- entering several email addresses or domains in one field
- a list of free-text tags or keywords
- pasting a comma-separated list that splits into items
Practices
| Guidance | Practice |
|---|---|
| Do | Render tags from useTagInput().tags, not value. It keeps removed tags until their exit animation ends. |
| Do | Pass validate to flag bad entries. A failing tag is kept and carries data-invalid. |
| Do | Pass name to submit the tags with a form. Each tag becomes a hidden input. |
| Don’t | Render TagInput.TagRemove outside a TagInput.Tag. It throws. |
API reference
TagInput.Root
A div that holds the tags and the draft text, and focuses the input when its empty space is pressed. Carries data-disabled and data-empty.
| Prop | Type | Description |
|---|---|---|
value | string[] | The tags, when controlled. |
defaultValue | string[] | The tags on mount, when uncontrolled.Default: [] |
onValueChange | (value: string[]) => void | Called with the new tags. |
inputValue | string | The draft text, when controlled. |
defaultInputValue | string | The draft text on mount, when uncontrolled.Default: '' |
onInputValueChange | (inputValue: string) => void | Called with the new draft text. |
validate | (value: string) => boolean | Returns false to mark a tag invalid. Does not block adding it. |
delimiters | string[] | Strings that split typed or pasted text into tags. Newlines and tabs always split.Default: [','] |
name | string | Submits each tag as a hidden input with this name. |
form | string | The id of the form the hidden inputs belong to. |
disabled | boolean | Blocks adding and removing tags.Default: false |
focusableWhenDisabled | boolean | Keeps the input focusable and read-only while disabled.Default: false |
TagInput.List
A div with role="list" that holds the tags.
TagInput.Tag
A div with role="listitem", reached with arrow keys. Backspace or Delete removes it. Carries data-value, data-invalid, data-disabled and the transition attributes, and renders nothing once it has exited.
| Prop | Type | Description |
|---|---|---|
value | string | The tag this element shows. |
TagInput.TagRemove
A button labelled Remove <value> that removes its tag, out of the tab order.
TagInput.Input
The text input for the draft. Its value is owned by the root.
Examples
Email list
function Tags() {
const { tags } = TagInput.useTagInput();
return (
<TagInput.List>
{tags.map(tag => (
<TagInput.Tag key={tag.value} value={tag.value}>
{tag.value}
<TagInput.TagRemove />
</TagInput.Tag>
))}
</TagInput.List>
);
}
<TagInput.Root name='emails' validate={isEmail}>
<Tags />
<TagInput.Input aria-label='Emails' />
</TagInput.Root>