Tags Input
A text field that turns typed or pasted text into removable tags, for free-form values such as topics or email addresses.JSX
<TagsInput aria-label="Tags" placeholder="Add a tag" />
Installation
Package
CLI (copy source)
pnpm
pnpm add @advui/corenpm
npm install @advui/coreUsage
import { Field, TagsInput } from '@advui/core'
<Field label="Topics">
<TagsInput value={topics} onValueChange={setTopics} placeholder="Add a topic" />
</Field>Examples
In a Field
Enter or a comma adds a topic; the field’s label names the text box.Preview
Code
react
tamagui
Validation
Email addresses separated by commas or spaces, up to five. A refused address stays in the text box and the field shows why.Preview
Code
ada@example.com
Sizes
Small, medium and large, as tall as an Input.Preview
Code
small
medium
large
API reference
TagsInput
A field box that wraps its chips and text box onto more lines as needed. Style and layout props go to the box; `id`, `aria-*` and the Field’s wiring go to the text box.| Prop | Type | Default | Description |
|---|---|---|---|
value | string[] | — | The tags, in order, when you control it. |
defaultValue | string[] | [] | Starting `value` when uncontrolled. |
onValueChange | (value: string[]) => void | — | Called with the new list when tags are added or removed. |
placeholder | string | — | Text in the empty text box. |
size | 'sm' | 'md' | 'lg' | 'md' | Height of a one-line field, matching Input: 32, 40 or 48px. |
separators | string[] | [','] | Characters that end a tag as you type them, besides Enter. Pasted text is split at them and every part is added. `[]` leaves only Enter. |
max | number | — | Most tags allowed. More are refused and stay in the text box. |
allowDuplicates | boolean | false | Allow the same tag twice. Otherwise a repeat stays in the text box. |
validate | (tag: string, value: string[]) => boolean | — | Return false to refuse a tag; it stays in the text box to be fixed. Tags are trimmed first. |
addOnBlur | boolean | true | Add the typed text when the field loses focus, so a form does not lose it. |
disabled | boolean | false | Disables the text box and the remove buttons. Also on inside a disabled Field or Form. |
invalid | boolean | false | Error border and `aria-invalid`. On inside a Field with an `error`. |
name | string | — | Field name for a native form: each tag submits under it.Web only. |
labels | Partial<TagsInputLabels> | — | Remove-button names (`remove(tag)`) and the announcements (`added(tags)`, `removed(tag)`), for translation. |
Accessibility
- The text box is a plain textbox named by
aria-labelor the Field’s label, with the Field’s help and error text as its description. - Each tag is a chip with a remove button named “Remove {tag}”. After the button removes its tag, focus moves to the text box on web, and to the next tag (or the previous one after the last) on iOS and Android.
- Added and removed tags are announced: through a polite live region on web, and with
AccessibilityInfo.announceForAccessibilityon iOS and Android. - Enter in an empty text box is not taken, so it still submits a form.
| Key | Action |
|---|---|
| Enter | Adds the typed text as a tag. |
| , (separators) | Adds the typed text as a tag. |
| Backspace | Removes the last tag when the text box is empty. |
| Tab | Moves through the remove buttons and the text box. |
Platform notes
Web
Presses on the box and on remove buttons keep focus in the text box, so half-typed text is not added by a blur.
iOS
The return key adds a tag and keeps the keyboard open.
Android
The return key adds a tag and keeps the keyboard open. Backspace in the empty text box removes the last tag with the on-screen keyboard; a hardware keyboard does not report it.