All components (244)

Tags

Fields · TagsInput

What it is and when to use it

A tags field: you type and each tag is closed with Enter or a comma, several can be pasted at once, and they are removed with their cross or with Backspace in the empty field. There is no list of options: the tag is whatever is typed.

When to use it

Keywords, guest emails, aliases: free values that the user makes up.
validate rejects a tag and says why (it stays typed so it can be corrected); transform normalises it before it is stored.
Duplicates (ignoring case) and more than max are not allowed. With name, one hidden field per tag travels.

When not to

Choosing among options that already exist: MultiSelect. A single one with free text: Combobox.

Keyboard: Enter, comma and semicolon close a tag; Backspace in an empty field removes the last one; arrow keys move between tags.

Accessibility: everything that happens (added, removed, already there, full) is announced in a live region. The error stays linked to the field.

What it looks like

Keywords

silver

ring

Up to five · 2 of 5

<TagsInput
  label="Keywords"
  placeholder="Type and press Enter"
  initialValue={["silver", "ring"]}
  max={5}
  hint="Up to five"
/>

Props

Import it with import { TagsInput } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	Required: names the field and the group of tags.
`allowsDuplicates`	`boolean`	With `true` it accepts the same tag twice. Not by default (ignoring case).
`className`	`string`	Merged with the library classes; it does not replace them.
`commitOnBlur`	`boolean`	Whether the text left typed when leaving the field becomes a tag. Yes by default.
`disabled`	`boolean`	—
`error`	`string`	Error from outside (from the server). It takes precedence over the one the field calculates.
`hint`	`string`	—
`initialValue`	`readonly string[]`	The tags at the start, without controlling them from outside.
`invalid`	`boolean`	—
`limitTags`	`number`	How many tags are shown while the field is at rest; the rest are summed up as "+N" and all of them appear when the field is entered. Without it all are shown.
`max`	`number`	The maximum number of tags allowed. Without it, as many as needed.
`name`	`string`	So that they travel in a native form: one hidden field per tag, with this name.
`onChange`	`(tags: readonly string[]) => void`	Notifies with the whole list every time it changes.
`placeholder`	`string`	—
`readOnly`	`boolean`	—
`renderTag`	`(tag: string) => ReactNode`	What is displayed for each tag, when it is more than its text.
`required`	`boolean`	—
`separators`	`readonly string[]`	The characters that close a tag when typed, in addition to Enter. Defaults to `,` and `;`.
`size`	`"sm" \| "md" \| "lg"`	—
`transform`	`(tag: string) => string`	Changes the tag before saving it (for example, to lowercase).
`validate`	`(tag: string) => string \| null`	Checks a tag before accepting it: returns the reason if it is not valid, or `null`.
`value`	`readonly string[]`	The tags, controlled from outside.
`variant`	`FieldVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: