Skip to content
Mosaic
On this page

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

GuidancePractice
DoPass a localized removeLabel. The default is English.
DoPass validate to mark bad entries invalid instead of dropping them, and show a Field.Error.
DoPass 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

PropTypeDescription
valuestring[]The tags, when controlled.
defaultValuestring[]The tags on mount.Default: []
onValueChange(value: string[]) => voidCalled with the new tags.
inputValuestringThe uncommitted draft, when controlled.
defaultInputValuestringThe draft on mount.Default: ''
onInputValueChange(inputValue: string) => voidCalled with the new draft.
validate(value: string) => booleanReturns false to mark a tag invalid. Invalid tags stay in value.
delimitersstring[]Characters that commit the draft as you type or paste.Default: [',']
namestringRenders one hidden input per tag with this name.
removeLabel(value: string) => stringEach remove button's accessible name.Default: `Remove ${value}`
requiredbooleanRequired 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>