Tag Input React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Tag Input is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import TagInput from @/components/ui/tag-input.

import { useState } from "react"
import { TagInput } from "@/components/ui/tag-input"

export function ListingTags() {
  const [tags, setTags] = useState(["bike", "vintage"])

  return (
    <TagInput
      label="Listing tags"
      description="Up to 8 tags, separated by commas."
      placeholder="Type and press Enter"
      value={tags}
      onValueChange={setTags}
      max={8}
      name="tags"
      suggestions={[
        { value: "bike", label: "bike" },
        { value: "vintage", label: "vintage" },
        { value: "trek", label: "trek" },
        { value: "city", label: "city" },
        { value: "sport", label: "sport" },
      ]}
    />
  )
}

Props

• labeldefault ""
  ReactNode

  Renders the field anatomy around the box: the label above it, linked to the text input; the box is a group named by it.

• descriptiondefault ""
  ReactNode

  Helper text under the box, linked with aria-describedby. At the limit it is replaced by labels.limit(max) when you pass none.

• errordefault ""
  ReactNode

  Replaces the description with the animated error and marks the field invalid. Rejected tags show their own message here until the text changes.

• requireddefault false
  boolean

  The red mark after the label and aria-required on the text input.

• invaliddefault false
  boolean

  The invalid look and aria-invalid without a message.

• disableddefault false
  boolean

  Dims the field, blocks typing, hides the × on chips and disables the hidden inputs.

• readOnlydefault false
  boolean

  Chips stay visible and focusable but cannot be removed, edited or added to; no suggestions.

• placeholderdefault "Add a tag"
  string

  Hint text while there are no tags; the input stays usable after. The demo passes Add a tag.

• value
  string[]

  The tags, controlled; pair it with onValueChange. A tag that equals a suggestion's value shows that option's label and icon.

• defaultValuedefault "[]"
  string[]

  The starting tags while uncontrolled; a form reset returns to them.

• onValueChange
  (tags: string[]) => void

  Fires with the new list after every add, remove, edit and clear.

• suggestions
  ListboxItems (TagInputSuggestion | TagInputSuggestionGroup)[]

  Autocomplete options filtered while typing (case and diacritics ignored, groups kept). Options already added leave the list. A picked option adds its value; typing an option's label exactly adds its value too.

• delimitersdefault "[",", ";"]"
  string[]

  Characters that add the current text as a tag, detected in the text itself so Android keyboards work. Enter always adds.

• validate
  (tag: string, tags: string[]) => (string | boolean)

  Runs after transform. false rejects with labels.invalid(tag), a string rejects with that message; the text stays in the field and shakes. tagValidators.email, .url and .hashtag are exported; with the email one the keyboard switches to email.

• transformdefault "trim + collapse spaces"
  (tag: string) => string

  Normalizes typed text before validation, e.g. lowercase and a leading #. The default trims and collapses spaces, which also runs after yours.

• labels
  Partial<TagInputLabels>

  Screen reader copy and messages, merged over the English defaults: tag(tag) the chip's name ("Tag bike, press Delete to remove"), remove(tag), added(tag), removed(tag), duplicate(tag), limit(max), invalid(tag), notInList(tag), clear ("Clear all"), suggestions ("Suggestions").

• onReject
  (tag: string, reason: "invalid" | "duplicate" | "limit" | "notInList") => void

  Called for every tag that was turned away, e.g. to show your own message when the control sits inside a <Field>.

• sizedefault "md"
  "sm" | "md" | "lg"

  Minimum height 32 / 40 / 48px (md 44px on touch) with 20 / 24 / 28px chips and 13 / 14 / 15px text (16px on phones). The box grows as chips wrap.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The box look shared with every input.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Box corners scaled with the size; chips follow (pill chips in a full box, square chips with none, 6px otherwise).

• chipVariantdefault "soft"
  "soft" | "outline" | "solid"

  The Badge variant of the chips.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Semantic color of the chips.

• colordefault ""
  string

  Any CSS color for the chips; replaces the tone. Empty uses the tone.

• maxdefault 0
  number

  Maximum number of tags. At the limit the text field hides, the keyboard shows Done and the description reads labels.limit(max). 0 means no limit.

• maxLengthdefault 0
  number

  Characters per tag; longer text is cut as you type or paste. 0 means no limit.

• backspacedefault "edit"
  "edit" | "select" | "remove"

  Backspace in the empty field: edit puts the last tag back as text, select highlights it first and a second press removes it, remove deletes it at once.

• editabledefault true
  boolean

  Double-click a chip, tap a focused chip, or press Enter or F2 on it to edit it in place. Emptying it removes the tag.

• addOnBlurdefault true
  boolean

  Leaving the field adds what was typed (validated like Enter).

• addOnPastedefault true
  boolean

  A pasted text with delimiters, new lines or tabs becomes several tags at once; off, it is pasted as plain text.

• allowDuplicatesdefault false
  boolean

  Off, a tag that already exists (compared without case or diacritics) is not added and the existing chip pulses.

• restrictToSuggestionsdefault false
  boolean

  Only suggestions can become tags: the first match is highlighted as you type and other text is rejected with labels.notInList.

• openOnFocusdefault false
  boolean

  Opens the suggestions as soon as the field is focused instead of when you type or press Arrow Down, and keeps them open after a pick.

• clearabledefault false
  boolean

  A Clear all × at the end of the box while there are tags; focus returns to the text.

• namedefault ""
  string

  One hidden input per tag with this name, so FormData.getAll(name) returns the list. The demo uses tags while empty.

• fieldProps
  Partial<FieldProps>

  Anything else for the Field wrapper: optional, labelAction, orientation, labelWidth, hideLabel.

• id
  string

  The text input's id. Defaults to useId(); inside a <Field> the Field's id wins.

• ref
  RefObject<HTMLInputElement | null> or (node) => void

  The text input. Every other native prop lands there too: inputMode, enterKeyHint, autoFocus, onBlur, onKeyDown (runs first; preventDefault skips the built-in keys), aria-*, data-*.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "root" | "box" | "tag" | "editor" | "input" | "clear" | "suggestions" | "list" | "option", string>>

  Extra classes for the parts: the field anatomy, the box, each chip, the in-place editor, the text input, the clear button and the suggestions panel, list and rows.

• className
  string

  Classes for the outermost element: the Field root when there is a label, description or error, else the tag input root.

Parts

FAQ

Used in

More React input components