Skip to content
Mosaic
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

GuidancePractice
DoRender tags from useTagInput().tags, not value. It keeps removed tags until their exit animation ends.
DoPass validate to flag bad entries. A failing tag is kept and carries data-invalid.
DoPass name to submit the tags with a form. Each tag becomes a hidden input.
Don’tRender 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.

PropTypeDescription
valuestring[]The tags, when controlled.
defaultValuestring[]The tags on mount, when uncontrolled.Default: []
onValueChange(value: string[]) => voidCalled with the new tags.
inputValuestringThe draft text, when controlled.
defaultInputValuestringThe draft text on mount, when uncontrolled.Default: ''
onInputValueChange(inputValue: string) => voidCalled with the new draft text.
validate(value: string) => booleanReturns false to mark a tag invalid. Does not block adding it.
delimitersstring[]Strings that split typed or pasted text into tags. Newlines and tabs always split.Default: [',']
namestringSubmits each tag as a hidden input with this name.
formstringThe id of the form the hidden inputs belong to.
disabledbooleanBlocks adding and removing tags.Default: false
focusableWhenDisabledbooleanKeeps 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.

PropTypeDescription
valuestringThe 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

TSX
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>