# TagInput

A field that turns typed and pasted entries into removable tags. A delimiter, Enter or blur commits the draft; entries are trimmed and duplicates dropped. Backspace or the reading-direction arrow at the start of the input moves to the last tag, and Backspace or Delete on a tag removes it. The ref and other props go to the text input (`cl-tag-input-input`). Inside a `Field` it takes the field id, label, disabled, required, invalid and message wiring.

## Use for

- entering several email addresses, such as invitations
- a list of free-text values, such as domains or keywords
- pasting a comma-separated list

## Practices

- Do: Pass a localized `removeLabel`. The default is English.
- Do: Pass `validate` to mark bad entries invalid instead of dropping them, and show a `Field.Error`.
- Do: Pass `name` to submit each tag as a hidden input in a native form.

## API reference

### TagInput

Renders a `div` with the tags (`cl-tag-input-list`) and the input. Each tag is a `cl-tag-input-tag` with a label (`cl-tag-input-tag-label`) and remove button (`cl-tag-input-tag-remove`), carrying `data-invalid` and `data-disabled`. The root carries `data-disabled` and `data-invalid`.

Slot: `cl-tag-input`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` |  | The tags, when controlled. |
| `defaultValue` | `string[]` | `[]` | The tags on mount. |
| `onValueChange` | `(value: string[]) => void` |  | Called with the new tags. |
| `inputValue` | `string` |  | The uncommitted draft, when controlled. |
| `defaultInputValue` | `string` | `''` | The draft on mount. |
| `onInputValueChange` | `(inputValue: string) => void` |  | Called with the new draft. |
| `validate` | `(value: string) => boolean` |  | Returns `false` to mark a tag invalid. Invalid tags stay in `value`. |
| `delimiters` | `string[]` | `[',']` | Characters that commit the draft as you type or paste. |
| `name` | `string` |  | Renders one hidden input per tag with this name. |
| `removeLabel` | `(value: string) => string` | `` `Remove ${value}` `` | Each remove button's accessible name. |
| `required` | `boolean` |  | Required while there are no tags. |

## Examples

### Email invitations

```tsx
<Field.Root>
  <Field.Label>{m.emailLabel}</Field.Label>
  <TagInput
    name='emailAddresses'
    delimiters={[',', ' ']}
    value={emails}
    onValueChange={setEmails}
    validate={isValidEmail}
    removeLabel={email => fill(m.removeEmail, { email })}
  />
</Field.Root>
```

## Related

- [Field](/docs/components/field.md)
- [Input](/docs/components/input.md)
