# Tags Input
URL: https://ark-ui.com/docs/components/tags-input
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/tags-input.mdx
A component that allows users to add tags to an input field.
---
## Anatomy
To set up the tags input correctly, you'll need to understand its anatomy and how we name its parts.
> Each part includes a `data-part` attribute to help identify them in the DOM.
## Examples
Learn how to use the `TagsInput` component in your project. Let's take a look at the most basic example:
**Example: basic**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const Basic = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const Basic = () => (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### Initial tags
To set the initial tag values, set the `defaultValue` prop.
**Example: initial-value**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const InitialValue = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const InitialValue = () => {
return (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### 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`.
**Example: max-with-overflow**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const MaxWithOverflow = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const MaxWithOverflow = () => {
return (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks (Max 3, Overflow Allowed)
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### 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.
**Example: controlled**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { useState } from 'react'
import { XIcon } from 'lucide-react'
export const Controlled = () => {
const [value, setValue] = useState(['vue', 'react'])
return (
<>
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
Current tags: {value.join(', ')}
```
### 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.
**Example: controlled-input-value**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { useState } from 'react'
import { XIcon } from 'lucide-react'
export const ControlledInputValue = () => {
const [inputValue, setInputValue] = useState('')
return (
Frameworks (Programmatic Control)
{#each tags().value as value, index (index)}
{value}
{/each}
```
### Read-only
Use the `readOnly` prop to make tags visible but not editable. Users can view tags but cannot add, remove, or modify
them.
**Example: readonly**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const Readonly = () => {
return (
{(tagsInput) => (
<>
Frameworks (Read-only)
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const Readonly = () => (
{(api) => (
<>
Frameworks (Read-only)
{(value, index) => (
{value()}
)}
)}
)
```
#### Vue
```vue
Frameworks (Read-only){{ value }}
```
#### Svelte
```svelte
Frameworks (Read-only)
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### Validating Tags
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.
**Example: validation**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
const TAG_PATTERN = /^[a-zA-Z0-9-]+$/
const validateTag = (details: { value: string[]; inputValue: string }) => {
const { value, inputValue } = details
if (!inputValue || inputValue.trim() === '') {
return false
}
if (value.includes(inputValue)) {
return false
}
if (inputValue.length < 3) {
return false
}
if (!TAG_PATTERN.test(inputValue)) {
return false
}
return true
}
export const Validation = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const Validation = () => {
return (
{
return !details.value.includes(details.inputValue)
}}
>
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
{
return !details.value.includes(details.inputValue)
}}
>
{#snippet render(tagsInput)}
Frameworks
{#each tagsInput().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### 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.
**Example: blur-behavior**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const BlurBehavior = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const BlurBehavior = () => {
return (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
{#snippet render(tagsInput)}
Frameworks
{#each tagsInput().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### 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
**Example: paste-behavior**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const PasteBehavior = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const PasteBehavior = () => {
return (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
{#snippet render(tagsInput)}
Frameworks
{#each tagsInput().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### Disable tag 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}`
**Example: disabled-editing**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const DisabledEditing = () => {
return (
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const DisabledEditing = () => {
return (
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks (Read-only)
{#snippet render(tags)}
{#each tags().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### Events
During the lifetime of the tags input interaction, here's a list of events we emit:
- `onValueChange` — invoked when the tag value changes.
- `onHighlightChange` — invoked when a tag has visual focus.
- `onValueInvalid` — invoked when the max tag count is reached or the `validate` function returns `false`.
**Example: on-event**
#### React
```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const OnEvent = () => {
return (
{
console.log('tags changed to:', details.value)
}}
onHighlightChange={(details) => {
console.log('highlighted tag:', details.highlightedValue)
}}
onValueInvalid={(details) => {
console.log('Invalid!', details.reason)
}}
max={3}
allowOverflow
validate={(details) => {
return !details.value.includes(details.inputValue)
}}
>
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const OnEvent = () => {
return (
{
console.log('tags changed to:', details.value)
}}
onHighlightChange={(details) => {
console.log('highlighted tag:', details.highlightedValue)
}}
onValueInvalid={(details) => {
console.log('Invalid!', details.reason)
}}
max={3}
allowOverflow
validate={(details) => {
return !details.value.includes(details.inputValue)
}}
>
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
{
console.log('tags changed to:', details.value)
}}
onHighlightChange={(details) => {
console.log('highlighted tag:', details.highlightedValue)
}}
onValueInvalid={(details) => {
console.log('Invalid!', details.reason)
}}
max={3}
allowOverflow
validate={(details) => {
return !details.value.includes(details.inputValue)
}}
>
{#snippet render(tagsInput)}
Frameworks
{#each tagsInput().value as value, index (index)}
{value}
{/each}
{/snippet}
```
### Using the Field Component
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.
**Example: with-field**
#### React
```tsx
import { Field } from '@ark-ui/react/field'
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const WithField = (props: Field.RootProps) => {
return (
{(tagsInput) => (
<>
Label
{tagsInput.value.map((value, index) => (
{value}
))}
)}
Additional InfoError Info
)
}
```
#### Solid
```tsx
import { Field } from '@ark-ui/solid/field'
import { TagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const WithField = (props: Field.RootProps) => {
return (
{(tagsInput) => (
<>
Label
{(value, index) => (
{value()}
)}
)}
Additional InfoError Info
)
}
```
#### Vue
```vue
Label{{ value }}Additional InfoError Info
```
#### Svelte
```svelte
{#snippet render(tagsInput)}
Label
{#each tagsInput().value as value, index (index)}
{value}
{/each}
{/snippet}
Additional InfoError Info
```
### Using the Root Provider
The `RootProvider` component provides a context for the tags-input. It accepts the value of the `useTags-input` hook.
You can leverage it to access the component state and methods from outside the tags-input.
**Example: root-provider**
#### React
```tsx
import { TagsInput, useTagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
export const RootProvider = () => {
const tagsInput = useTagsInput()
return (
<>
{(tagsInput) => (
<>
Frameworks
{tagsInput.value.map((value, index) => (
{value}
))}
)}
)
}
```
#### Solid
```tsx
import { TagsInput, useTagsInput } from '@ark-ui/solid/tags-input'
import { XIcon } from 'lucide-solid'
import { Index } from 'solid-js'
export const RootProvider = () => {
const tagsInput = useTagsInput()
return (
<>
{(api) => (
<>
Frameworks
{(value, index) => (
{value()}
)}
)}
)
}
```
#### Vue
```vue
Frameworks{{ value }}
```
#### Svelte
```svelte
Frameworks
{#each tags().value as value, index (index)}
{value}
{/each}
```
> If you're using the `RootProvider` component, you don't need to use the `Root` component.
## Guides
### Navigating and Editing tags
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
**Component API Reference**
#### React
**Root Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | 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` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | 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` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Callback fired when the input value is updated |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the tag values is updated |
| `onValueInvalid` | `(details: ValidityChangeDetails) => void` | No | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| `value` | `string[]` | No | The controlled tag value |
**Root Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ClearTrigger Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |
**Control Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Control Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemInput Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `string | number` | Yes | |
| `value` | `string` | Yes | |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | |
**Item Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
**ItemText Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemText Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
**Label Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Label Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTagsInputReturn` | Yes | |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
#### Solid
**Root Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | 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` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | 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` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `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
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Callback fired when the input value is updated |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the tag values is updated |
| `onValueInvalid` | `(details: ValidityChangeDetails) => void` | No | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| `value` | `string[]` | No | The controlled tag value |
**Root Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ClearTrigger Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |
**Control Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Control Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemInput Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `string | number` | Yes | |
| `value` | `string` | Yes | |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | |
**Item Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
**ItemText Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemText Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
**Label Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Label Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTagsInputReturn` | Yes | |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
#### Vue
**Root Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | 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` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | 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` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `modelValue` | `string[]` | No | The v-model value of the tags input |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
**Root Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ClearTrigger Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |
**Control Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Control Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Input Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemInput Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemPreview Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `string | number` | Yes | |
| `value` | `string` | Yes | |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | |
**Item Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
**ItemText Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**ItemText Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
**Label Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
**Label Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `TagsInputApi` | Yes | |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
#### Svelte
**Root Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | 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` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | 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` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Callback fired when the input value is updated |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the tag values is updated |
| `onValueInvalid` | `(details: ValidityChangeDetails) => void` | No | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `ref` | `Element` | No | |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| `value` | `string[]` | No | The controlled tag value |
**Root Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**ClearTrigger Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |
**Context Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseTagsInputReturn]>` | Yes | |
**Control Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**Control Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**Input Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**Input Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 |
**ItemContext Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseTagsInputItemContext]>` | Yes | |
**ItemDeleteTrigger Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**ItemInput Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**ItemPreview Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**ItemPreview Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | |
| `value` | `string` | Yes | |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | |
| `ref` | `Element` | No | |
**Item Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
**ItemText Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**ItemText Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |
**Label Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
**Label Data Attributes:**
| Attribute | Value |
|-----------|-------|
| `[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 Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTagsInputReturn` | Yes | |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No | |
### Context
These are the properties available when using `UtagsUinput.Context`, `useUtagsUinputContext` hook or `useUtagsUinput` hook.
**API:**
| Property | Type | Description |
|----------|------|-------------|
| `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