elements
Manual UI Templates TagsInput

TagsInput

elements man ui/templates/tags-input

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

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