Tags Input

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add tags-input

Usage#

Anatomy#

One component, built from two: the Input frame and Chip. The frame keeps every Input token (border, brand focus ring, destructive state, the size ladder) and trades its fixed height for a minimum, so a second row of chips grows it.

import { TagsInput } from "@/components/ui/tags-input"

<TagsInput />

// renders
// <InputRoot>                the field frame, min-height = size
//   <div role="grid">        display: contents, chips and input share one wrap
//     <Chip asChild>
//       <div role="row">     data-slot="tags-input-tag", one gridcell inside
//         label
//         <ChipRemove />     "Remove {tag}"
//   <InputField />           the text you type

Sizes#

The Input ladder: sm 32px, md 36px and lg 40px at rest. Chips step with it (20px in sm, 24px above) and sit an even inset from the frame, so their corners stay concentric. Unsized, the field takes its default from the domain or the container, the same as Input and Button.

Wrapping#

Chips wrap inside the field and the frame grows a row at a time. The text input keeps a minimum width and drops to the next row when the last one is full. A tag longer than the field truncates instead of overflowing.

Delimiters & paste#

delimiters decides what ends a tag. Single characters split typed and pasted text; key names commit on that key. The default, comma and Enter, keeps spaces inside a tag. Enter on an empty input still submits the form. A pasted list is split on the character delimiters and on line breaks, so a column copied from a spreadsheet arrives as one tag per row.

Validation#

validate answers for each tag. true keeps it, "invalid" keeps it as a destructive outline chip (the frame turns destructive with it), and false turns it away: the text stays in the input so it can be repaired, and the frame gives the house rejection shake. Duplicates and tags past max are rejected the same way, and onReject tells you why.

The shake is three damped swings on ease-sine, 2 to 4px by size, and only the frame moves: the label and hint hold still so the message is readable at once. It is skipped under prefers-reduced-motion. The verdict also runs on every render with the tag’s index and the whole list, so a limit like “free seats” can mark the tags past it.

Max#

max caps the list. A tag past it is rejected with the shake, and the typed text waits in the input until a chip is removed.

Controlled#

Pass value and onValueChange for the list, and inputValue with onInputValueChange for the text being typed. Both work uncontrolled with defaultValue.

States#

hasError paints the destructive frame and is read from a surrounding Field. readOnly keeps the chips readable and reachable with the arrow keys but drops the remove buttons. disabled dims the whole field.

Keyboard#

The text input is the field’s only tab stop. From an empty input, Backspace selects the last chip and a second Backspace removes it, so one stray key never deletes a tag. ArrowLeft at the start of the input moves onto the chips; on a chip, ArrowLeft / ArrowRight move between them, Home jumps to the first, End or Escape return to the input, and Backspace / Delete remove it. Typing a letter on a chip goes back to the input.

The chips follow the tag-group pattern: a grid named by the field’s label, one row per chip with its text and remove button in a single gridcell, so a focusable control never nests inside an option. The selected chip carries aria-selected, an invalid one says so to screen readers, and each remove button is named “Remove tag” but kept out of the tab order, since Backspace and Delete do its job from the keyboard. Additions, removals and rejections are announced through a polite live region.

Labels#

The words the field says on its own (the remove buttons, the announcements, the fallback name) come from LabelsProvider: tags, removeTag, invalidTag, tagAdded, tagRemoved and tagRejected. A removeLabel prop wins over the provider.

API reference#

FAQ#