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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
value | string[] | The tags, when controlled. |
defaultValue | string[] | The tags on mount.Default: [] |
onValueChange | (value: string[]) => void | Called with the new tags. |
inputValue | string | The uncommitted draft, when controlled. |
defaultInputValue | string | The draft on mount.Default: '' |
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.Default: [','] |
name | string | Renders one hidden input per tag with this name. |
removeLabel | (value: string) => string | Each remove button's accessible name.Default: `Remove ${value}` |
required | boolean | Required while there are no tags. |
Examples
Email invitations
<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>