# TagsInput

Type a list of tags into one field: add, edit, delete and paste them from the keyboard.

```ehtml Example
import { TagsInput } from "@elements/ui/tags-input";

<TagsInput value={post.tags} placeholder="Add a tag" attrs={{ "aria-label": "Tags" }} />
<TagsInput value={invite.emails} delimiter={/[,;\s]/} addOnPaste validate={isEmail} max={10} />
```

## Parts

| Part | What it is |
|---|---|
| `.tags-input` | The root. |
| `.tags-input-control` | The bordered box. |
| `.tags-input-item` | One tag. |
| `.tags-input-item-text` | Its text. |
| `.tags-input-item-delete` | Its delete button. |
| `.tags-input-item-input` | The editor while a tag is edited. |
| `.tags-input-input` | The text input. |
| `.tags-input-clear` | Clears every tag. |
| `.tags-input-listbox` | The suggestions popup, role=listbox, in the top layer. |
| `.tags-input-option` | One suggestion, role=option. |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string[]` (two-way) | `[]` | The tags. |
| `inputValue` | `string` (two-way) | `""` | The text typed but not yet a tag. |
| `placeholder` | `string` | `""` | Shown in the empty text input. |
| `delimiter` | `string \| RegExp` | `","` | Typing or pasting it ends a tag. A piece the rules refuse stays in the input. |
| `max` | `number` | `Infinity` | Most tags allowed. |
| `allowOverflow` | `boolean` | `false` | Allows tags past max and marks the field invalid. |
| `maxLength` | `number \| undefined` | `undefined` | Most characters per tag. |
| `allowDuplicates` | `boolean` | `false` | Allows the same tag twice. |
| `addOnPaste` | `boolean` | `false` | A paste becomes tags, split on the delimiter and newlines; refused pieces stay in the input. |
| `blurBehavior` | `"" \| "add" \| "clear"` | `""` | On blur: keep the typed text, add it as a tag, or clear it. |
| `editable` | `boolean` | `true` | Enter or a double click edits a tag in place. |
| `suggestions` | `string[]` | `[]` | Options offered in a listbox under the input as you type. Chosen ones are not offered again. |
| `disabledTags` | `string[]` | `[]` | Tags that cannot be deleted or edited; Clear keeps them. |
| `clearable` | `boolean` | `true` | Shows a button that clears every tag. |
| `validate` | `((details: { inputValue: string; value: string[] }) => boolean) \| null` | `null` | Return false to refuse a tag. |
| `sanitizeValue` | `(value: string) => string` | `trim` | Cleans a tag before it is checked. |
| `name` | `string` | `""` | Submits the tags joined by the delimiter. |
| `form` | `string` | `""` | The id of the form the tags belong to. |
| `disabled` | `boolean` | `false` | Not interactive. |
| `readonly` | `boolean` | `false` | Tags can be read and highlighted, not changed. |
| `required` | `boolean` | `false` | The form will not submit without a tag. |
| `invalid` | `boolean` | `false` | Marks the field invalid. |
| `translations` | `Partial<TagsInputTranslations>` | `{}` | Announcements and button labels, for other languages. |
| `class` | `string` | `""` | Extra classes on the root. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the text input: id, aria-label, autofocus, data-\*. |
| `onValueChange` | `(value: string[]) => void` | `() => {}` | After a tag is added, edited, deleted or cleared. |
| `onInputValueChange` | `(inputValue: string) => void` | `() => {}` | As the typed text changes. |
| `onHighlightChange` | `(value: string \| null) => void` | `() => {}` | When the highlighted tag changes. |
| `onValueInvalid` | `(details: { reason: "rangeOverflow" \| "invalidTag" }) => void` | `() => {}` | When max or validate refuses a tag. |
| `onFocusOutside` | `(e: FocusEvent) => void` | `() => {}` | When focus leaves the field. |
| `onPointerDownOutside` | `(e: PointerEvent) => void` | `() => {}` | On a press outside while the field is focused. |

## Keyboard

| Keys | Action |
|---|---|
| `Enter` | Adds the typed text as a tag; on a highlighted tag, edits it. |
| `Delimiter (,)` | Adds the text before it. |
| `ArrowLeft / ArrowRight` | Moves the highlight between tags and back to the input. |
| `Home / End` | First tag / back to the input. |
| `Backspace` | At the start of the input: highlights the last tag, then deletes it. |
| `Delete` | Deletes the highlighted tag. |
| `Escape` | Closes the suggestions, clears the highlight or cancels an edit. |
| `ArrowDown / ArrowUp` | With suggestions: opens the list, or moves through its options. |
| `Enter on an option` | With suggestions: adds the highlighted option as a tag. |
| `Ctrl/Cmd + V` | With addOnPaste, pastes as tags. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-focus` | present while the input has focus | root, control |
| `data-empty` | present with no tags (on the input: no text) | root, input |
| `data-invalid` | present when invalid (the root also past max) | root, control, input |
| `data-disabled` | present when disabled (an item also when listed in disabledTags) | root, control, item, item text |
| `data-readonly` | present when read-only | root, control, input, clear |
| `data-highlighted` | present on the highlighted tag | item, item text, delete |
| `data-editing` | present while a tag is edited | item |
| `data-invalid` | present on an edit the rules refused, until it changes | item, item input |
| `data-value` | the tag | item |
| `data-highlighted` | present on the highlighted suggestion | option |

## Accessibility

- Focus stays in the text input; arrow keys move a highlight across the tags, so typing is never more than one key away.
- Adding, deleting, editing and highlighting a tag are announced in a polite live region.
- With suggestions the text input is a combobox (aria-expanded, aria-controls, aria-autocomplete=list) and the highlighted option is its aria-activedescendant.
- Delete buttons are named "Delete tag X"; they are out of the tab order because Backspace and Delete do their job.

## See also

- [Slider](slider): Pick a value or a range by dragging thumbs along a track, with full keyboard support.
- [NumberInput](number-input): A number field with stepper buttons, keyboard steps, formatting, wheel and scrub.
- [PasswordInput](password-input): A password field with a button that shows and hides what was typed.
- [InputOTP](input-otp): A one-time code in separate slots, with paste, SMS autofill and a pattern.
- [ColorPicker](color-picker): Pick a color with an area, channel sliders, inputs, swatches and the eye dropper.
- [FileUpload](file-upload): Drop, paste or browse for files; see them listed with previews, sizes, errors and progress.