Tags Input
Type free-text tags into a field that shows each one as a removable tag before the text.
Press Enter or type a comma to add a tag.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/tags-inputComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/formField is installed with Tags Input.
Usage
import { TagsInput } from "@/siteplane/components/tags-input";
<TagsInput aria-label="Tags" defaultValue={["Design", "Research"]} />;A Tags Input takes words that people type, such as labels, keywords or email addresses, and shows each one as a Tag in the field, before the text. Enter adds the text as a tag, and so does a comma. Each tag ends with a remove button. To choose from a known list of options instead, use a Combobox with chips, which looks the same.
Composition
TagsInput
├── TagGroup → Tag with its remove button, one per tag
├── text input
└── help icon or alert icon (tooltip, showInvalidIcon)TagsInput renders these parts itself; it takes no children. The tags are Tags, on the surface color of a card with the kit's hairline around them, as the chips of a Combobox are. They flow in the field's row with the text after them, and the field grows a row whenever the tags fill one. The text keeps at least 48 px and moves to a row of its own where less room is left beside the tags.
Adding and removing tags
Enter adds the text as a tag and never sends the form. The delimiter, a comma by default, adds the text before it as you type, and pasted text with delimiters adds every part before the last one, while the rest stays in the field. A new tag is trimmed. An empty text adds nothing, and a text that the field does not take, such as a duplicate, stays in the field so it can be corrected.
Each tag's remove button takes it out. Its name is “Remove” and the tag, such as “Remove Design”; pass removeLabel, a function of the tag, to name it otherwise, or translate it once for the application with the chip.remove message of SiteplaneLocaleProvider, which also names the remove buttons of a Tag, a Badge and a Combobox chip. A press on the field outside its tags puts the caret in the text.
Keyboard
Backspace in the empty text, or the Left arrow at its start, moves focus to the last tag. The Left and Right arrows move between the tags, and Backspace or Delete removes the focused tag. The Right arrow on the last tag returns to the text, and once the last tag is gone the text takes focus. While a person composes text with an input method, Enter belongs to the composition and adds no tag.
Duplicates, limits and validation
A text that is a tag already is not added; set allowDuplicates to allow it. maxTags sets the most tags the field holds, and validate accepts or rejects each new tag: it receives the trimmed text and returns true to add it. Set delimiter to another string, such as ";", or to null for tags that contain commas, such as cities with their region. Say what the field takes in a FieldDescription, since a rejected tag only stays in the text.
Up to five email addresses, separated by commas.
Sizes
Omit size to inherit the provider's control size. Each size sets the field's height for one row of tags, 36, 40, 44 or 48 px, and the text of an Input of that size. The tags take the tag size of their field, as the chips of a Combobox do: sm tags, 24 px with 12 px text, in an sm field, md tags, 24 px with 14 px text, in an md or lg field, and xl tags, 32 px with 16 px text, in an xl field. The tags stand 6 px apart, in a row and from row to row, as the chips of a Combobox do, and the text starts 8 px after the last tag. variant="soft" gives the field the soft surface of an Input: a subtle gray fill under the same edge, and the page background while it has focus.
Help and invalid state
tooltip puts a help icon at the end of the field, as on an Input, that shows its text in a Tooltip on hover and keyboard focus. While the field is invalid, an alert icon takes its place, so pass the help text in every state; showInvalidIcon={false} turns the alert icon off. Set invalid on the Field and explain the problem with FieldError. A disabled field fades as a whole, takes the light gray fill of a disabled field and its tags cannot be removed.
Controlled value
Pass value and onValueChange to own the tags, for example to show how many are left or to clear them all. onValueChange receives the new list whenever a tag is added or removed.
3 of 6 keywords
Form integration
Set name, or name on the Field around it, to send the tags with a form: each tag is one entry of that name in the form data, which FormData.getAll reads as a list. The text that is being typed is not sent. form names a form elsewhere on the page. required marks the field as required for assistive technology and for the Field's requiredIndicator, but a form is not stopped when it is sent without a tag; check the list in your submit handler. The tags do not reset with their form: control them and set them back in the form's onReset.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Tags | readonly string[] | unset | The tags, controlled. |
Tags | readonly string[] | [] | The tags the field starts with, uncontrolled. |
Tags | (tags: string[]) => void | unset | Called with the new tags when a tag is added or removed. |
Tags | string | unset | Shown in the text while the field holds no tag. |
Tags | sm | md | lg | xl | provider / sm | The control size of the field and the size of its tags. |
Tags | default | soft | default | Field surface, as on Input and ComboboxChips: soft lays a subtle fill under the edge and takes the page background while focused. |
Tags | string | null | "," | Typing or pasting it adds the text before it as a tag, as Enter does. null turns it off. |
Tags | boolean | false | Adds a text that is a tag already. |
Tags | number | unset | The most tags the field holds; a further text is not added. |
Tags | (tag: string) => boolean | unset | Accepts or rejects a new tag; it receives the trimmed text. |
Tags | boolean | false | Disables the text and the tags' remove buttons. A disabled Field disables the field too. |
Tags | string | unset | The name of the tags in the form data, one entry per tag. A Field's name comes first. |
Tags | string | unset | The id of the form that the tags belong to. |
Tags | boolean | false | Marks the field as required for assistive technology and for requiredIndicator. It does not stop a form sent without a tag. |
Tags | ReactNode | unset | Help text behind a help icon at the end of the field, shown in a Tooltip on hover and keyboard focus. |
Tags | boolean | true | Shows an alert icon at the end of the field while it is invalid, in place of the help icon. |
Tags | (tag: string) => string | Remove and the tag | The name of each tag's remove button. Unset, the chip.remove message of SiteplaneLocaleProvider names it with the tag. |
Tags | string | unset | The id of the text input, which a label's htmlFor names. |
Tags | string | unset | The name of the text input, and of the tags without a Field label. Without either, the tags are named by the label of the tagsInput messages, Tags in English. |
Tags | string | unset | Go to the text input; aria-labelledby also names the tags. |
Tags | AriaAttributes["aria-invalid"] | unset | Marks the field invalid outside a Field, with its invalid frame and alert icon. |
TagsInputProps extends the props of a div, except children,
defaultValue, id and onChange, and the root accepts a ref. The root is a
group with data-slot="tags-input", data-size and, while disabled,
data-disabled; className styles it. The tags are a
TagGroup of Tags at the tag size of the field,
and the text is the kit's Input, which takes a Field's label, description, error
and state. With a name, every tag renders a hidden input. TagsInputProps is
exported.
Usage notes
Use a Tags Input for values that people make up themselves, such as labels, keywords or a list of email addresses. When every value comes from a known list, a Combobox with chips lets people search and choose instead of typing. To show tags without a field, or to let people select them, use a Tag Group.
Name the field with a FieldLabel or aria-label. Screen readers meet the tags as a grid of rows, each with its remove button, followed by the text. A placeholder is not a label, and it shows only while the field holds no tag. A floating label is not available: keep the label above the field. In a right-to-left page the Left and Right arrows between the text and the tags are not mirrored, and the field's height changes at once when a row of tags comes or goes.