# Tags Input

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

Project tags input

[Complete TSX file](/examples/tags-input/default.tsx)

```tsx
"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

Complete [one-time setup](/docs/installation/) first.

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

With npm: `npx shadcn@4.18.0 add @siteplane/tags-input`. [Registry JSON](/registry/tags-input.json) lists source files and dependencies.

For this page’s examples, also install:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/form
```

Field is installed with Tags Input.

## Usage

```tsx
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](/docs/components/tag-group/) 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](/docs/components/combobox/#multiple-selection) with chips, which looks the same.

## Composition

```text
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](/docs/components/tag-group/), 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](/docs/customization/localization/), 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.

Email invitations with a limit and validation

[Complete TSX file](/examples/tags-input/rules.tsx)

```tsx
"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](/docs/components/input/#sizes) 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](/docs/components/input/#variants): a subtle gray fill under the same edge, and the page background while it has focus.

Tags input sizes

[Complete TSX file](/examples/tags-input/sizes.tsx)

```tsx
"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](/docs/components/input/#tooltip), 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](/docs/components/input/#disabled-read-only-and-invalid) and its tags cannot be removed.

Disabled and invalid tags inputs

[Complete TSX file](/examples/tags-input/states.tsx)

```tsx
"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.

Keywords with a count and a clear button

[Complete TSX file](/examples/tags-input/controlled.tsx)

```tsx
"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`.

Topics sent with a form

[Complete TSX file](/examples/tags-input/form.tsx)

```tsx
"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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| TagsInput.value | readonly string[] | unset | The tags, controlled. |
| TagsInput.defaultValue | readonly string[] | [] | The tags the field starts with, uncontrolled. |
| TagsInput.onValueChange | (tags: string[]) => void | unset | Called with the new tags when a tag is added or removed. |
| TagsInput.placeholder | string | unset | Shown in the text while the field holds no tag. |
| TagsInput.size | sm \| md \| lg \| xl | provider / sm | The control size of the field and the size of its tags. |
| TagsInput.variant | 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. |
| TagsInput.delimiter | string \| null | "," | Typing or pasting it adds the text before it as a tag, as Enter does. null turns it off. |
| TagsInput.allowDuplicates | boolean | false | Adds a text that is a tag already. |
| TagsInput.maxTags | number | unset | The most tags the field holds; a further text is not added. |
| TagsInput.validate | (tag: string) => boolean | unset | Accepts or rejects a new tag; it receives the trimmed text. |
| TagsInput.disabled | boolean | false | Disables the text and the tags' remove buttons. A disabled Field disables the field too. |
| TagsInput.name | string | unset | The name of the tags in the form data, one entry per tag. A Field's name comes first. |
| TagsInput.form | string | unset | The id of the form that the tags belong to. |
| TagsInput.required | boolean | false | Marks the field as required for assistive technology and for requiredIndicator. It does not stop a form sent without a tag. |
| TagsInput.tooltip | ReactNode | unset | Help text behind a help icon at the end of the field, shown in a Tooltip on hover and keyboard focus. |
| TagsInput.showInvalidIcon | boolean | true | Shows an alert icon at the end of the field while it is invalid, in place of the help icon. |
| TagsInput.removeLabel | (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. |
| TagsInput.id | string | unset | The id of the text input, which a label's htmlFor names. |
| TagsInput.aria-label | 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. |
| TagsInput.aria-labelledby / aria-describedby | string | unset | Go to the text input; aria-labelledby also names the tags. |
| TagsInput.aria-invalid | 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](/docs/components/tag-group/) 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](/source/tags-input).

## 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](/docs/components/combobox/#multiple-selection) 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](/docs/components/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.
