# Tags Input

URL: https://ark-ui.com/docs/components/tags-input
LLM: https://ark-ui.com/llms.txt/components/tags-input

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

---



## Anatomy



```tsx
<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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const Basic = () => {
  return (
    <TagsInput.Root className={styles.Root}>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### 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.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/tags-input.module.css'

export const Controlled = () => {
  const [value, setValue] = useState<string[]>(['React', 'Solid'])

  return (
    <TagsInput.Root className={styles.Root} value={value} onValueChange={(details) => setValue(details.value)}>
      <TagsInput.Context>
        {(api) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {api.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### 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.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/tags-input.module.css'

export const ControlledInputValue = () => {
  const [inputValue, setInputValue] = useState('')

  return (
    <div className="stack">
      <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
        <button className={button.Root} type="button" onClick={() => setInputValue('React')}>
          Set to "React"
        </button>
        <button className={button.Root} type="button" onClick={() => setInputValue('')}>
          Clear Input
        </button>
        <span style={{ fontSize: '14px' }}>Current: "{inputValue}"</span>
      </div>

      <TagsInput.Root
        className={styles.Root}
        inputValue={inputValue}
        onInputValueChange={(details) => setInputValue(details.inputValue)}
      >
        <TagsInput.Context>
          {(tagsInput) => (
            <>
              <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
              <TagsInput.Control className={styles.Control}>
                {tagsInput.value.map((value, index) => (
                  <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                    <TagsInput.ItemPreview className={styles.ItemPreview}>
                      <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                      <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                        <XIcon />
                      </TagsInput.ItemDeleteTrigger>
                    </TagsInput.ItemPreview>
                    <TagsInput.ItemInput className={styles.ItemInput} />
                  </TagsInput.Item>
                ))}
                <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
                <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                  <XIcon />
                </TagsInput.ClearTrigger>
              </TagsInput.Control>
            </>
          )}
        </TagsInput.Context>
        <TagsInput.HiddenInput />
      </TagsInput.Root>
    </div>
  )
}
```

### 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.

```tsx
import { TagsInput, useTagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const RootProvider = () => {
  const tagsInput = useTagsInput()
  return (
    <div className="stack">
      <TagsInput.RootProvider className={styles.Root} value={tagsInput}>
        <TagsInput.Context>
          {(api) => (
            <>
              <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
              <TagsInput.Control className={styles.Control}>
                {api.value.map((value, index) => (
                  <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                    <TagsInput.ItemPreview className={styles.ItemPreview}>
                      <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                      <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                        <XIcon />
                      </TagsInput.ItemDeleteTrigger>
                    </TagsInput.ItemPreview>
                    <TagsInput.ItemInput className={styles.ItemInput} />
                  </TagsInput.Item>
                ))}
                <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
                <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                  <XIcon />
                </TagsInput.ClearTrigger>
              </TagsInput.Control>
            </>
          )}
        </TagsInput.Context>
        <TagsInput.HiddenInput />
      </TagsInput.RootProvider>

      <output>values: {JSON.stringify(tagsInput.value)}</output>
    </div>
  )
}
```

### 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.

```tsx
import { Field } from '@ark-ui/react/field'
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import field from 'styles/field.module.css'
import styles from 'styles/tags-input.module.css'

export const WithField = () => {
  return (
    <Field.Root className={field.Root}>
      <TagsInput.Root className={styles.Root}>
        <TagsInput.Context>
          {(tagsInput) => (
            <>
              <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
              <TagsInput.Control className={styles.Control}>
                {tagsInput.value.map((value, index) => (
                  <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                    <TagsInput.ItemPreview className={styles.ItemPreview}>
                      <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                      <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                        <XIcon />
                      </TagsInput.ItemDeleteTrigger>
                    </TagsInput.ItemPreview>
                    <TagsInput.ItemInput className={styles.ItemInput} />
                  </TagsInput.Item>
                ))}
                <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
                <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                  <XIcon />
                </TagsInput.ClearTrigger>
              </TagsInput.Control>
            </>
          )}
        </TagsInput.Context>
        <TagsInput.HiddenInput />
      </TagsInput.Root>
      <Field.HelperText className={field.HelperText}>Additional Info</Field.HelperText>
      <Field.ErrorText className={field.ErrorText}>Error Info</Field.ErrorText>
    </Field.Root>
  )
}
```

### 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`.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const MaxWithOverflow = () => {
  return (
    <TagsInput.Root className={styles.Root} max={3} allowOverflow>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### 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.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

const DELIMITER_PATTERN = /[,;\s]/

export const Delimiter = () => {
  return (
    <TagsInput.Root className={styles.Root} delimiter={DELIMITER_PATTERN}>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks (add with comma, semicolon, or space)</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add tag" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Disabled

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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const Disabled = () => {
  return (
    <TagsInput.Root className={styles.Root} defaultValue={['React', 'Solid', 'Vue']} disabled>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Invalid

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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const Invalid = () => {
  return (
    <TagsInput.Root className={styles.Root} invalid>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Max Length

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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const MaxTagLength = () => {
  return (
    <TagsInput.Root className={styles.Root} maxLength={10}>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks (Max 10 characters)</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Read-only

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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const Readonly = () => {
  return (
    <TagsInput.Root className={styles.Root} defaultValue={['React', 'Solid', 'Vue']} readOnly>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### 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.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

const TAG_PATTERN = /^[a-zA-Z0-9-]+$/

const validateTag = ({ value, inputValue }: { value: string[]; inputValue: string }) =>
  !!inputValue?.trim() && !value.includes(inputValue) && inputValue.length >= 3 && TAG_PATTERN.test(inputValue)

export const Validation = () => {
  return (
    <TagsInput.Root className={styles.Root} validate={validateTag}>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks (Min 3 chars, alphanumeric)</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### 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.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const BlurBehavior = () => {
  return (
    <TagsInput.Root className={styles.Root} blurBehavior="add">
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

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

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const PasteBehavior = () => {
  return (
    <TagsInput.Root className={styles.Root} addOnPaste delimiter=",">
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Disable Editing

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

<kbd>Enter</kbd>. To disable this behavior, pass `editable={false}`

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const DisabledEditing = () => {
  return (
    <TagsInput.Root className={styles.Root} editable={false}>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
            <TagsInput.Control className={styles.Control}>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                  <TagsInput.ItemPreview className={styles.ItemPreview}>
                    <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                      <XIcon />
                    </TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput className={styles.ItemInput} />
                </TagsInput.Item>
              ))}
              <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
              <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                <XIcon />
              </TagsInput.ClearTrigger>
            </TagsInput.Control>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}
```

### Programmatic Control

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

```tsx
import { TagsInput, useTagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/tags-input.module.css'

export const ProgrammaticControl = () => {
  const tagsInput = useTagsInput()

  return (
    <div className="stack">
      <div style={{ display: 'flex', gap: '8px' }}>
        <button className={button.Root} type="button" onClick={() => tagsInput.addValue('React')}>
          Add React
        </button>
        <button className={button.Root} type="button" onClick={() => tagsInput.addValue('Solid')}>
          Add Solid
        </button>
        <button className={button.Root} type="button" onClick={() => tagsInput.setValue(['Vue', 'Svelte'])}>
          Set to Vue & Svelte
        </button>
        <button className={button.Root} type="button" onClick={() => tagsInput.clearValue()}>
          Clear All
        </button>
      </div>

      <TagsInput.RootProvider className={styles.Root} value={tagsInput}>
        <TagsInput.Context>
          {(api) => (
            <>
              <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
              <TagsInput.Control className={styles.Control}>
                {api.value.map((value, index) => (
                  <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                    <TagsInput.ItemPreview className={styles.ItemPreview}>
                      <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                      <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                        <XIcon />
                      </TagsInput.ItemDeleteTrigger>
                    </TagsInput.ItemPreview>
                    <TagsInput.ItemInput className={styles.ItemInput} />
                  </TagsInput.Item>
                ))}
                <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
                <TagsInput.ClearTrigger className={styles.ClearTrigger}>
                  <XIcon />
                </TagsInput.ClearTrigger>
              </TagsInput.Control>
            </>
          )}
        </TagsInput.Context>
        <TagsInput.HiddenInput />
      </TagsInput.RootProvider>
    </div>
  )
}
```

### Sanitize Value

Use the `sanitizeValue` prop to normalize tag values before they're added. This runs on every new tag — useful for
trimming whitespace, converting to lowercase, or any other formatting you need.

```tsx
import { TagsInput } from '@ark-ui/react/tags-input'
import { XIcon } from 'lucide-react'
import styles from 'styles/tags-input.module.css'

export const SanitizeValue = () => (
  <TagsInput.Root className={styles.Root} sanitizeValue={(value) => value.trim().toLowerCase()}>
    <TagsInput.Context>
      {(tagsInput) => (
        <>
          <TagsInput.Label className={styles.Label}>Email Addresses</TagsInput.Label>
          <TagsInput.Control className={styles.Control}>
            {tagsInput.value.map((value, index) => (
              <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
                <TagsInput.ItemPreview className={styles.ItemPreview}>
                  <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                    <XIcon />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput className={styles.ItemInput} />
              </TagsInput.Item>
            ))}
            <TagsInput.Input placeholder="Add email" className={styles.Input} />
            <TagsInput.ClearTrigger className={styles.ClearTrigger}>
              <XIcon />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        </>
      )}
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
)
```

### 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.

```tsx
import { Combobox, useCombobox, useListCollection } from '@ark-ui/react/combobox'
import { useFilter } from '@ark-ui/react/locale'
import { Portal } from '@ark-ui/react/portal'
import { TagsInput, useTagsInput } from '@ark-ui/react/tags-input'
import { CheckIcon, XIcon } from 'lucide-react'
import { useId } from 'react'
import combobox from 'styles/combobox.module.css'
import styles from 'styles/tags-input.module.css'

export const WithCombobox = () => {
  const { contains } = useFilter({ sensitivity: 'base' })

  const { collection, filter } = useListCollection({
    initialItems: ['React', 'Solid', 'Vue', 'Svelte', 'Angular', 'Preact', 'Next.js', 'Astro', 'Nuxt'],
    filter: contains,
  })

  const uid = useId()

  const tagsInput = useTagsInput({
    ids: { input: `input_${uid}`, control: `control_${uid}` },
  })

  const comboboxApi = useCombobox({
    ids: { input: `input_${uid}`, control: `control_${uid}` },
    collection,
    onInputValueChange(details) {
      filter(details.inputValue)
    },
    value: [],
    allowCustomValue: true,
    onValueChange: (details) => {
      if (details.value[0]) {
        tagsInput.addValue(details.value[0])
      }
    },
    selectionBehavior: 'clear',
  })

  return (
    <Combobox.RootProvider value={comboboxApi}>
      <TagsInput.RootProvider className={styles.Root} value={tagsInput}>
        <TagsInput.Label className={styles.Label}>Frameworks</TagsInput.Label>
        <TagsInput.Control className={styles.Control}>
          {tagsInput.value.map((value, index) => (
            <TagsInput.Item key={index} index={index} value={value} className={styles.Item}>
              <TagsInput.ItemPreview className={styles.ItemPreview}>
                <TagsInput.ItemText className={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger className={styles.ItemDeleteTrigger}>
                  <XIcon />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput className={styles.ItemInput} />
            </TagsInput.Item>
          ))}
          <Combobox.Input asChild>
            <TagsInput.Input placeholder="Add Framework" className={styles.Input} />
          </Combobox.Input>
          <TagsInput.ClearTrigger className={styles.ClearTrigger}>
            <XIcon />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
        <TagsInput.HiddenInput />
      </TagsInput.RootProvider>

      <Portal>
        <Combobox.Positioner>
          <Combobox.Content className={combobox.Content}>
            <Combobox.Empty className={combobox.Item}>No frameworks found</Combobox.Empty>
            {collection.items.map((item) => (
              <Combobox.Item className={combobox.Item} key={item} item={item}>
                <Combobox.ItemText className={combobox.ItemText}>{item}</Combobox.ItemText>
                <Combobox.ItemIndicator className={combobox.ItemIndicator}>
                  <CheckIcon />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            ))}
          </Combobox.Content>
        </Combobox.Positioner>
      </Portal>
    </Combobox.RootProvider>
  )
}
```

## Guides

### Navigation

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 <kbd>Enter</kbd> or double-clicking on the tag will put it in edit mode, allowing the user change its value
  and press <kbd>Enter</kbd> to commit the changes.
- Pressing <kbd>Delete</kbd> or <kbd>Backspace</kbd> will delete the tag that has _visual_ focus.

## API Reference

### Props

### Root

#### Props

**`addOnPaste`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to add a tag when you paste values into the tag input

**`allowDuplicates`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to allow duplicate tags.

**`allowOverflow`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoFocus`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the input should be auto-focused

**`blurBehavior`**
Type: `'clear' | 'add'`
Required: false
Default Value: `undefined`
Description: 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`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The initial tag input value when rendered.
Use when you don't need to control the tag input value.

**`defaultValue`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The initial tag value when rendered.
Use when you don't need to control the tag value.

**`delimiter`**
Type: `string | RegExp`
Required: false
Default Value: `","`
Description: 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`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the tags input should be disabled

**`editable`**
Type: `boolean`
Required: false
Default Value: `true`
Description: Whether a tag can be edited after creation, by pressing `Enter` or double clicking.

**`form`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The associate form of the underlying input element.

**`id`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The unique identifier of the machine.

**`ids`**
Type: `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
}>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the tags input. Useful for composition.

**`inputValue`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The controlled tag input's value

**`invalid`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the tags input is invalid

**`max`**
Type: `number`
Required: false
Default Value: `Infinity`
Description: The max number of tags

**`maxLength`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The max length of the input.

**`name`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The name attribute for the input. Useful for form submissions

**`onFocusOutside`**
Type: `(event: FocusOutsideEvent) => void`
Required: false
Default Value: `undefined`
Description: Function called when the focus is moved outside the component

**`onHighlightChange`**
Type: `(details: HighlightChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback fired when a tag is highlighted by pointer or keyboard navigation

**`onInputValueChange`**
Type: `(details: InputValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback fired when the input value is updated

**`onInteractOutside`**
Type: `(event: InteractOutsideEvent) => void`
Required: false
Default Value: `undefined`
Description: Function called when an interaction happens outside the component

**`onPointerDownOutside`**
Type: `(event: PointerDownOutsideEvent) => void`
Required: false
Default Value: `undefined`
Description: Function called when the pointer is pressed down outside the component

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback fired when the tag values is updated

**`onValueInvalid`**
Type: `(details: ValidityChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback fired when the max tag count is reached or the `validateTag` function returns `false`

**`placeholder`**
Type: `string`
Required: false
Default Value: `undefined`
Description: The placeholder text for the input

**`readOnly`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the tags input should be read-only

**`required`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Whether the tags input is required

**`sanitizeValue`**
Type: `(value: string) => string`
Required: false
Default Value: `(value) => value.trim()`
Description: Function to sanitize the tag value before adding.
Useful for trimming whitespace, normalizing case, or stripping special characters.

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`validate`**
Type: `(details: ValidateArgs) => boolean`
Required: false
Default Value: `undefined`
Description: Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values.

**`value`**
Type: `string[]`
Required: false
Default Value: `undefined`
Description: The controlled tag value

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: tags-input
**`data-part`**: clear-trigger
**`data-readonly`**: Present when read-only

### Control

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Input

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: tags-input
**`data-part`**: item-delete-trigger
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

### ItemInput

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### ItemPreview

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`index`**
Type: `string | number`
Required: true
Default Value: `undefined`
Description: undefined

**`value`**
Type: `string`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`disabled`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: undefined

#### Data Attributes

**`data-scope`**: tags-input
**`data-part`**: item
**`data-value`**: The value of the item
**`data-disabled`**: Present when disabled

### ItemText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: tags-input
**`data-part`**: item-text
**`data-disabled`**: Present when disabled
**`data-highlighted`**: Present when highlighted

### Label

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`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

**`value`**
Type: `UseTagsInputReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

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

**`ArrowLeft`**
Description: Moves focus to the previous tag item

**`ArrowRight`**
Description: Moves focus to the next tag item

**`Backspace`**
Description: Deletes the tag item that has visual focus or the last tag item

**`Enter`**
Description: <span>When a tag item has visual focus, it puts the tag in edit mode.<br />When the input has focus, it adds the value to the list of tags</span>

**`Delete`**
Description: Deletes the tag item that has visual focus

**`Control + V`**
Description: When `addOnPaste` is set. Adds the pasted value as a tags