Tags Input

A component that allows users to add tags to an input field.

Frameworks

React

Solid

Vue

Svelte

Anatomy

<TagsInput.Root>
  <TagsInput.Label />
  <TagsInput.Control>
    <TagsInput.Item>
      <TagsInput.ItemPreview>
        <TagsInput.ItemText />
        <TagsInput.ItemDeleteTrigger />
      </TagsInput.ItemPreview>
      <TagsInput.ItemInput />
    </TagsInput.Item>
    <TagsInput.Input />
    <TagsInput.ClearTrigger />
  </TagsInput.Control>
  <TagsInput.HiddenInput />
</TagsInput.Root>

Examples

Controlled

Use the value and onValueChange props to programmatically control the tags input's state. This allows you to manage the tags array externally and respond to changes.

Controlled Input Value

Use the inputValue and onInputValueChange props to control the text input field independently. This is useful for clearing the input or pre-filling it programmatically.

Root Provider

An alternative way to control the tags input is to use the RootProvider component and the useTagsInput hook. This way you can access the state and methods from outside the component.

Field

The Field component helps manage form-related state and accessibility attributes of a tags input. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Max Tags

To limit the number of tags within the component, you can set the max property to the limit you want. The default value is Infinity.

When the tag reaches the limit, new tags cannot be added except the allowOverflow prop is set to true.

Custom Delimiter

Use the delimiter prop with a regex pattern to specify multiple characters that can separate tags. By default, only the Enter key creates tags.

Disabled

Use the disabled prop to make the tags input non-interactive. Users won't be able to add, remove, or edit tags.

Invalid

Use the invalid prop to mark the tags input as invalid for form validation purposes.

Max Length

Use the maxLength prop to limit the number of characters allowed per tag. This prevents users from creating overly long tags.

Read-only

Use the readOnly prop to make tags visible but not editable. Users can view tags but cannot add, remove, or modify them.

Validation

Before a tag is added, the validate function is called to determine whether to accept or reject a tag.

A common use-case for validating tags is preventing duplicates or validating the data type.

Blur behavior

When the tags input is blurred, you can configure the action the component should take by passing the blurBehavior prop.

add — Adds the tag to the list of tags.
clear — Clears the tags input value.

Paste behavior

To add a tag when a arbitrary value is pasted in the input element, pass the addOnPaste prop.

When a value is pasted, the component will:

check if the value is a valid tag based on the validate option
split the value by the delimiter option passed

Disable Editing

by default the tags can be edited by double-clicking on the tag or focusing on them and pressing

Enter. To disable this behavior, pass editable={false}

Programmatic Control

Use the useTagsInput hook with RootProvider to access the component's API methods like addValue(), setValue(), and clearValue() for full programmatic control.

Combobox

Combine TagsInput with Combobox to create an autocomplete tags input. This pattern uses shared IDs between both components and the asChild prop to compose the inputs together.

Guides

When the input has an empty value or the caret is at the start position, the tags can be selected by using the arrow left and arrow right keys. When "visual" focus in on any tag:

Pressing Enter or double-clicking on the tag will put it in edit mode, allowing the user change its value and press Enter to commit the changes.
Pressing Delete or Backspace will delete the tag that has visual focus.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`addOnPaste`	`false`	`boolean` Whether to add a tag when you paste values into the tag input
`allowOverflow`		`boolean` Whether to allow tags to exceed max. In this case, we'll attach `data-invalid` to the root
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`autoFocus`		`boolean` Whether the input should be auto-focused
`blurBehavior`		`'clear' \| 'add'` The behavior of the tags input when the input is blurred - `"add"`: add the input value as a new tag - `"clear"`: clear the input value
`defaultInputValue`		`string` The initial tag input value when rendered. Use when you don't need to control the tag input value.
`defaultValue`		`string[]` The initial tag value when rendered. Use when you don't need to control the tag value.
`delimiter`	`','`	`string \| RegExp` The character that serves has: - event key to trigger the addition of a new tag - character used to split tags when pasting into the input
`disabled`		`boolean` Whether the tags input should be disabled
`editable`	`true`	`boolean` Whether a tag can be edited after creation, by pressing `Enter` or double clicking.
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string input: string hiddenInput: string clearBtn: string label: string control: string item: (opts: ItemProps) => string itemDeleteTrigger: (opts: ItemProps) => string itemInput: (opts: ItemProps) => string }>` The ids of the elements in the tags input. Useful for composition.
`inputValue`		`string` The controlled tag input's value
`invalid`		`boolean` Whether the tags input is invalid
`max`	`Infinity`	`number` The max number of tags
`maxLength`		`number` The max length of the input.
`name`		`string` The name attribute for the input. Useful for form submissions
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onHighlightChange`		`(details: HighlightChangeDetails) => void` Callback fired when a tag is highlighted by pointer or keyboard navigation
`onInputValueChange`		`(details: InputValueChangeDetails) => void` Callback fired when the input value is updated
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onValueChange`		`(details: ValueChangeDetails) => void` Callback fired when the tag values is updated
`onValueInvalid`		`(details: ValidityChangeDetails) => void` Callback fired when the max tag count is reached or the `validateTag` function returns `false`
`readOnly`		`boolean` Whether the tags input should be read-only
`required`		`boolean` Whether the tags input is required
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`validate`		`(details: ValidateArgs) => boolean` Returns a boolean that determines whether a tag can be added. Useful for preventing duplicates or invalid tag values.
`value`		`string[]` The controlled tag value

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	root
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only
`[data-disabled]`	Present when disabled
`[data-focus]`	Present when focused
`[data-empty]`	Present when the content is empty

ClearTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	clear-trigger
`[data-readonly]`	Present when read-only

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	control
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-invalid]`	Present when invalid
`[data-focus]`	Present when focused

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Input

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	input
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only
`[data-empty]`	Present when the content is empty

ItemDeleteTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	item-delete-trigger
`[data-disabled]`	Present when disabled
`[data-highlighted]`	Present when highlighted

ItemInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

ItemPreview

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	item-preview
`[data-value]`	The value of the item
`[data-disabled]`	Present when disabled
`[data-highlighted]`	Present when highlighted

Item

Renders a <div> element.

Prop	Default	Type
`index`		`string \| number`
`value`		`string`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`disabled`		`boolean`

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	item
`[data-value]`	The value of the item
`[data-disabled]`	Present when disabled

ItemText

Renders a <span> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	item-text
`[data-disabled]`	Present when disabled
`[data-highlighted]`	Present when highlighted

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	tags-input
`[data-part]`	label
`[data-disabled]`	Present when disabled
`[data-invalid]`	Present when invalid
`[data-readonly]`	Present when read-only
`[data-required]`	Present when required

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseTagsInputReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`empty`	`boolean` Whether the tags are empty
`inputValue`	`string` The value of the tags entry input.
`value`	`string[]` The value of the tags as an array of strings.
`valueAsString`	`string` The value of the tags as a string.
`count`	`number` The number of the tags.
`atMax`	`boolean` Whether the tags have reached the max limit.
`setValue`	`(value: string[]) => void` Function to set the value of the tags.
`clearValue`	`(id?: string) => void` Function to clear the value of the tags.
`addValue`	`(value: string) => void` Function to add a tag to the tags.
`setValueAtIndex`	`(index: number, value: string) => void` Function to set the value of a tag at the given index.
`setInputValue`	`(value: string) => void` Function to set the value of the tags entry input.
`clearInputValue`	`VoidFunction` Function to clear the value of the tags entry input.
`focus`	`VoidFunction` Function to focus the tags entry input.
`getItemState`	`(props: ItemProps) => ItemState` Returns the state of a tag

Accessibility

Keyboard Support

Key	Description
`ArrowLeft`	Moves focus to the previous tag item
`ArrowRight`	Moves focus to the next tag item
`Backspace`	Deletes the tag item that has visual focus or the last tag item
`Enter`	When a tag item has visual focus, it puts the tag in edit mode. When the input has focus, it adds the value to the list of tags
`Delete`	Deletes the tag item that has visual focus
`Control + V`	When `addOnPaste` is set. Adds the pasted value as a tags

Tags Input

Anatomy

Examples

Controlled

Controlled Input Value

Root Provider

Field

Max Tags

Custom Delimiter

Disabled

Invalid

Max Length

Read-only

Validation

Blur behavior

Paste behavior

Disable Editing

Programmatic Control

Combobox

Guides

Navigation

API Reference

Props

Root

ClearTrigger

Control

HiddenInput

Input

ItemDeleteTrigger

ItemInput

ItemPreview

Item

ItemText

Label

RootProvider

Context

API

Accessibility

Keyboard Support

Contact Us