# TagInput

Headless, unstyled text input that turns entries into a list of string tags. Enter, a delimiter, paste or blur adds the trimmed text; blanks and duplicates are dropped. Backspace or the reading-start arrow at the start of the input moves into the tags. `TagInput.useTagInput()` reads the tags from inside the root.

## Use for

- entering several email addresses or domains in one field
- a list of free-text tags or keywords
- pasting a comma-separated list that splits into items

## Practices

- Do: Render tags from `useTagInput().tags`, not `value`. It keeps removed tags until their exit animation ends.
- Do: Pass `validate` to flag bad entries. A failing tag is kept and carries `data-invalid`.
- Do: Pass `name` to submit the tags with a form. Each tag becomes a hidden input.
- Don't: Render `TagInput.TagRemove` outside a `TagInput.Tag`. It throws.

## API reference

### TagInput.Root

A `div` that holds the tags and the draft text, and focuses the input when its empty space is pressed. Carries `data-disabled` and `data-empty`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` |  | The tags, when controlled. |
| `defaultValue` | `string[]` | `[]` | The tags on mount, when uncontrolled. |
| `onValueChange` | `(value: string[]) => void` |  | Called with the new tags. |
| `inputValue` | `string` |  | The draft text, when controlled. |
| `defaultInputValue` | `string` | `''` | The draft text on mount, when uncontrolled. |
| `onInputValueChange` | `(inputValue: string) => void` |  | Called with the new draft text. |
| `validate` | `(value: string) => boolean` |  | Returns `false` to mark a tag invalid. Does not block adding it. |
| `delimiters` | `string[]` | `[',']` | Strings that split typed or pasted text into tags. Newlines and tabs always split. |
| `name` | `string` |  | Submits each tag as a hidden input with this name. |
| `form` | `string` |  | The `id` of the form the hidden inputs belong to. |
| `disabled` | `boolean` | `false` | Blocks adding and removing tags. |
| `focusableWhenDisabled` | `boolean` | `false` | Keeps the input focusable and read-only while disabled. |

### TagInput.List

A `div` with `role="list"` that holds the tags.

### TagInput.Tag

A `div` with `role="listitem"`, reached with arrow keys. Backspace or Delete removes it. Carries `data-value`, `data-invalid`, `data-disabled` and the transition attributes, and renders nothing once it has exited.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The tag this element shows. |

### TagInput.TagRemove

A `button` labelled `Remove <value>` that removes its tag, out of the tab order.

### TagInput.Input

The text `input` for the draft. Its value is owned by the root.

## Examples

### Email list

```tsx
function Tags() {
  const { tags } = TagInput.useTagInput();
  return (
    <TagInput.List>
      {tags.map(tag => (
        <TagInput.Tag key={tag.value} value={tag.value}>
          {tag.value}
          <TagInput.TagRemove />
        </TagInput.Tag>
      ))}
    </TagInput.List>
  );
}

<TagInput.Root name='emails' validate={isEmail}>
  <Tags />
  <TagInput.Input aria-label='Emails' />
</TagInput.Root>
```
