Siteplane UI

Tags Input

Type free-text tags into a field that shows each one as a removable tag before the text.

Markdown

Press Enter or type a comma to add a tag.

"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { TagsInput } from "@/siteplane/components/tags-input";

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Project tags</FieldLabel>
      <TagsInput
        defaultValue={["Design", "Research"]}
        placeholder="Add a tag"
        tooltip="Tags help people find this project in search."
      />
      <FieldDescription>
        Press Enter or type a comma to add a tag.
      </FieldDescription>
    </Field>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/tags-input

Complete 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/form

Field 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.

"use client";

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { TagsInput } from "@/siteplane/components/tags-input";

const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Invite by email</FieldLabel>
      <TagsInput
        maxTags={5}
        placeholder="name@example.com"
        validate={(tag) => emailPattern.test(tag)}
      />
      <FieldDescription>
        Up to five email addresses, separated by commas.
      </FieldDescription>
    </Field>
  );
}

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.

"use client";

import { Field, FieldLabel } from "@/siteplane/components/field";
import { TagsInput } from "@/siteplane/components/tags-input";

const sizes = [
  { size: "sm", label: "small" },
  { size: "md", label: "medium" },
  { size: "lg", label: "large" },
  { size: "xl", label: "extra large" },
] as const;

export default function Example() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      {sizes.map(({ size, label }) => (
        <Field key={size}>
          <FieldLabel>Skills, {label}</FieldLabel>
          <TagsInput defaultValue={["Research", "Writing"]} size={size} />
        </Field>
      ))}
    </div>
  );
}

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.

Use three labels or fewer.
"use client";

import { Field, FieldError, FieldLabel } from "@/siteplane/components/field";
import { TagsInput } from "@/siteplane/components/tags-input";

export default function Example() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <Field disabled>
        <FieldLabel>Labels</FieldLabel>
        <TagsInput defaultValue={["Billing", "Priority"]} />
      </Field>
      <Field invalid>
        <FieldLabel>Labels</FieldLabel>
        <TagsInput
          defaultValue={["Billing", "Priority", "Refund", "Escalated"]}
          tooltip="Labels sort incoming tickets into queues."
        />
        <FieldError match>Use three labels or fewer.</FieldError>
      </Field>
    </div>
  );
}

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

"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { TagsInput } from "@/siteplane/components/tags-input";

const limit = 6;

export default function Example() {
  const [keywords, setKeywords] = useState(["pricing", "invoices", "refunds"]);

  return (
    <div className="grid w-full max-w-sm gap-3">
      <Field>
        <FieldLabel>Search keywords</FieldLabel>
        <TagsInput
          maxTags={limit}
          onValueChange={setKeywords}
          placeholder="Add a keyword"
          value={keywords}
        />
        <FieldDescription>
          {keywords.length} of {limit} keywords
        </FieldDescription>
      </Field>
      <div>
        <Button
          disabled={keywords.length === 0}
          onClick={() => setKeywords([])}
          size="xs"
          variant="outline"
        >
          Clear keywords
        </Button>
      </div>
    </div>
  );
}

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.

Each topic is sent as its own entry.

"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/siteplane/components/field";
import { Form } from "@/siteplane/components/form";
import { TagsInput } from "@/siteplane/components/tags-input";

const initialTopics = ["Billing", "Onboarding"];

export default function Example() {
  const [topics, setTopics] = useState(initialTopics);
  const [sent, setSent] = useState("");

  return (
    <Form
      className="grid w-full max-w-sm gap-4"
      onReset={() => {
        setTopics(initialTopics);
        setSent("");
      }}
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget).getAll("topics");
        setSent(
          data.length > 0 ? `Saved topics: ${data.join(", ")}.` : "No topics.",
        );
      }}
    >
      <Field name="topics">
        <FieldLabel>Help center topics</FieldLabel>
        <TagsInput
          onValueChange={setTopics}
          placeholder="Add a topic"
          value={topics}
        />
        <FieldDescription>
          Each topic is sent as its own entry.
        </FieldDescription>
      </Field>
      <div className="flex gap-2">
        <Button type="submit">Save</Button>
        <Button type="reset" variant="outline">
          Reset
        </Button>
      </div>
      <p className="min-h-5 text-muted-foreground text-sm" role="status">
        {sent}
      </p>
    </Form>
  );
}

API reference

Component properties
PropTypeDefaultDescription
TagsInput.valuereadonly string[]unsetThe tags, controlled.
TagsInput.defaultValuereadonly string[][]The tags the field starts with, uncontrolled.
TagsInput.onValueChange(tags: string[]) => voidunsetCalled with the new tags when a tag is added or removed.
TagsInput.placeholderstringunsetShown in the text while the field holds no tag.
TagsInput.sizesm | md | lg | xlprovider / smThe control size of the field and the size of its tags.
TagsInput.variantdefault | softdefaultField surface, as on Input and ComboboxChips: soft lays a subtle fill under the edge and takes the page background while focused.
TagsInput.delimiterstring | null","Typing or pasting it adds the text before it as a tag, as Enter does. null turns it off.
TagsInput.allowDuplicatesbooleanfalseAdds a text that is a tag already.
TagsInput.maxTagsnumberunsetThe most tags the field holds; a further text is not added.
TagsInput.validate(tag: string) => booleanunsetAccepts or rejects a new tag; it receives the trimmed text.
TagsInput.disabledbooleanfalseDisables the text and the tags' remove buttons. A disabled Field disables the field too.
TagsInput.namestringunsetThe name of the tags in the form data, one entry per tag. A Field's name comes first.
TagsInput.formstringunsetThe id of the form that the tags belong to.
TagsInput.requiredbooleanfalseMarks the field as required for assistive technology and for requiredIndicator. It does not stop a form sent without a tag.
TagsInput.tooltipReactNodeunsetHelp text behind a help icon at the end of the field, shown in a Tooltip on hover and keyboard focus.
TagsInput.showInvalidIconbooleantrueShows an alert icon at the end of the field while it is invalid, in place of the help icon.
TagsInput.removeLabel(tag: string) => stringRemove and the tagThe name of each tag's remove button. Unset, the chip.remove message of SiteplaneLocaleProvider names it with the tag.
TagsInput.idstringunsetThe id of the text input, which a label's htmlFor names.
TagsInput.aria-labelstringunsetThe 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.
TagsInput.aria-labelledby / aria-describedbystringunsetGo to the text input; aria-labelledby also names the tags.
TagsInput.aria-invalidAriaAttributes["aria-invalid"]unsetMarks 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.

Read the installed source.

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.