Tags Input

Anatomy

You render the tags yourself, from the value. The root owns that value and everything that changes it; the list is presentation — a div dressed as an Input — and each item finds its position by looking its value up in the root's array. Upstream's separate text and delete parts are folded into TagsInputItem, so there is nothing to compose inside a tag.

import {
  TagsInput,
  TagsInputClear,
  TagsInputInput,
  TagsInputItem,
  TagsInputLabel,
  TagsInputList,
} from '@comitor/ui'

<TagsInput value={tags} onValueChange={setTags}>
  {/* A <label> wired to the text field */}
  <TagsInputLabel>Labels</TagsInputLabel>

  {/* The box people see — Input's border and focus ring. Tags and the field share it. */}
  <TagsInputList>
    {tags.map((tag) => (
      // One per tag: the text, then a ✕ button named "Remove <tag>"
      <TagsInputItem key={tag} value={tag}>
        {tag}
      </TagsInputItem>
    ))}
    <TagsInputInput placeholder="Add a label…" />
  </TagsInputList>

  {/* Optional. Rendered only while there are tags, and it ships with no content. */}
  <TagsInputClear>Clear all</TagsInputClear>
</TagsInput>

Labels on a task

The everyday case: free text, committed with Enter or a comma, capped with max. Add a label, then press Backspace in the empty field — once highlights the last tag, twice removes it — and walk the tags with ← and →. With editable, double-click a tag (or highlight it and press Enter) to rename it in place.

• Refusals are silent unless you speak. At the limit, on a duplicate, or when onValidate says no, the entry is refused and onInvalid receives it. The component itself shows nothing: a failed validator or a duplicate sets data-invalid on the root and the field, which nothing styles, and the limit sets nothing at all — the sentence under this field is the demo's own.
• Duplicates are exact matches after trimming: Design and design are two tags. A duplicate typed with Enter is cleared from the field as if it had been added; every other refusal typed with Enter leaves the text where it was, ready to correct.
• max is a count, not a disabled state. At five labels the field still takes text — the sixth is refused on Enter — so the demo drops its placeholder and says so.
• The validator here refuses only empty strings. Without it, a space followed by Enter adds an empty tag — see Known limitations.

Email recipients

Addresses are validated before they become tags, the ones that fail are reported, and a list pasted from a mail client is taken apart. Type minh@comitor and press Enter — it stays in the field, with the reason below. Then copy the list above the field and paste it in.

• onValidate sees the trimmed text for every way in — Enter, the delimiter, Tab with addOnTab, leaving the field with blurBehavior="add", pasted pieces and in-place edits.
• This demo owns paste. addOnPaste reports nothing for pasted pieces that fail validation — they vanish — and splits on one delimiter only. Its onPaste on TagsInputInput runs before the component's and calls preventDefault(), then splits on commas, semicolons and line breaks, pulls the address out of Name <address>, and lists what it could not use. A single address with no separator is left to paste as ordinary text.
• blurBehavior="add" commits a valid address when focus leaves the field. Without it, an address someone typed and then tabbed away from stays in the field and is never sent.
• Case: the validator refuses an address already on the list in any case, and onValueChange lowercases what it stores. The component's own duplicate check is case-sensitive, so a mail field has to do this itself.
• aria-invalid, the red border and the role="alert" message are all the app's — see Accessibility.

Pasting a comma-separated list

When lists arrive comma-separated — tags copied from a spreadsheet or another record — addOnPaste splits the pasted text on delimiter. Copy the line above the field, click into it and paste. Then paste the same line a second time.

• First paste: pieces are trimmed, empty ones dropped and repeats collapsed — apac lands once. enterprise is already on the account, so it goes to onInvalid instead.
• Second paste: nothing is added. The limit is checked before anything else and counts every piece, repeats included — five tags plus five pieces is over eight — so the whole paste is refused and onInvalid receives the entire pasted string, not a tag.
• delimiter is also what typing listens for: the field commits when the last character typed equals it. Keep it to one character — a longer one still splits a paste but never fires while typing.
• Without addOnPaste a paste is plain text: apac, renewal-q4 becomes a single tag, comma and all, when Enter is pressed.

What the port guarantees

The keyboard, paste, in-place editing and the hidden form input are the headless core's; the file in the package is a styled wrapper. These are the places where it deliberately does not match upstream.

• Every ✕ has a name. deleteLabel(value) reads Remove q3-launch by default. Upstream pointed the button's aria-labelledby at the tag's own text, so a screen reader heard q3-launch, button — a button that sounds like the tag, not like removing it. Because aria-labelledby beats aria-label in the name computation, the port removes it rather than adding a label beside it.
• A disabled ✕ never takes focus. Upstream set tabIndex={-1} only on enabled buttons — backwards. The working buttons left the Tab order (on purpose: the keyboard removes tags from the text field) while disabled ones joined it, focusable and inert. The port pins -1 in both states; a screen reader's browse mode still reaches them.
• Right-to-left follows your DirectionProvider. @diceui/shared keeps a private direction context the package cannot export, so Radix's <DirectionProvider dir="rtl"> — where every other component here gets its direction — never reached the field. The port reads Radix's direction and passes it down as dir (your own dir still wins), and ← and → swap as they should.
• No prohibited ARIA on a tag. Upstream named each tag — a role-less div — with aria-labelledby, which ARIA 1.2 forbids on the generic role (axe: aria-prohibited-attr). The text is inside the tag, so nothing is lost.
• It lines up with Input. The list wears Input's border recipe — border-input at rest, --control-edge-strong on hover, --primary-ink and a ring-2 ring-ring/50 while focus is anywhere inside — and hovering a focused field no longer repaints the focus colour. Empty, it is Input's 36px (min-h-9 py-1.5, down from upstream's min-h-10 py-2), so it sits in a form row without a step.
• It fills its container. Upstream pinned the root at w-[380px], the width of its demo page. Here the root is w-full like Input, and the text field gets min-w-0 so an input's intrinsic width no longer pushes tags onto a new line early.
• Disabled looks disabled. disabled: never matches a div, and upstream's peer-disabled: never matched the label, which comes before the input. The box now dims through has-[input:disabled] — the real :disabled state, the one WCAG 1.4.3 and 1.4.11 exempt — and the label through in-data-disabled.

Language

Tags Input ships almost no text. The label, the placeholder and whatever you put in the clear button are yours, so they follow your own copy. The one string the package owns is the name of each ✕ button — invisible on screen, which is why the preview reads it back out of the DOM. Switch the language and watch it change.

• Namespace tagsInput, one key: deleteLabel — Remove {value} in English, Xoá thẻ {value} in the built-in Vietnamese table (comitorMessagesVi.tagsInput). It is a function because the tag sits inside the sentence, and the words around it move from language to language.
• Precedence: the deleteLabel prop on TagsInputItem → the nearest ComitorLocaleProvider → English. There is no labels object and no DEFAULT_*_LABELS constant for this component.
• The provider changes strings, not the lang attribute that tells a screen reader how to pronounce them. Set it on <html> in the app; the preview sets it on its own wrapper.
• Where the provider goes, and how locale is chosen: Get started → Set the language.

'use client' // deleteLabel is a function — it cannot come from a Server Component

import { ComitorLocaleProvider, TagsInputItem, type ComitorMessagesOverride } from '@comitor/ui'

// One field: the prop on the item beats the provider.
<TagsInputItem value={address} deleteLabel={(value) => `Remove recipient ${value}`}>
  {address}
</TagsInputItem>

// The whole app: override the namespace once. Module-level, so the reference is stable.
const MESSAGES: ComitorMessagesOverride = {
  tagsInput: { deleteLabel: (value) => `Remove the “${value}” tag` },
}

<ComitorLocaleProvider locale="en" messages={MESSAGES}>{children}</ComitorLocaleProvider>

Props

TagsInput — the headless core's props, plus the port's dir bridge. Every other div attribute passes through.

TagsInputItem:

TagsInputInput — every input attribute, and:

TagsInputClear — a <button type="button">:

TagsInputLabel is a <label> already wired to the text field, and TagsInputList a div; both take className and nothing of their own.

Known limitations

All of these are in the headless core; the workaround is what an app can do today.

• Moving between tags is not announced. ← and → highlight a tag with data-highlighted and aria-current, but focus stays in the text field and the core does not use aria-activedescendant, so a screen reader says nothing. Removal still works for everyone — every ✕ is a named button in browse mode — but if a screen depends on keyboard tag editing, offer the same actions somewhere that is announced.
• A disabled tag is not safe from the keyboard. The core walks tag positions counting only enabled tags, so when a disabled tag is not the last one, Backspace can highlight it and remove it. Its ✕ ignores clicks but is not a disabled button either. Keep locked tags — system labels, say — outside the field, as Badges.
• Blank tags. A space and then Enter (or a comma) adds an empty tag, and editing a tag down to nothing stores an empty one. Refuse them: onValidate={(v) => v.length > 0} — the value arrives trimmed. Every demo on this page does.
• The delimiter forgets. Typing the delimiter clears the field even when the entry is refused; Enter leaves refused text in place. If people can commit with a comma, show the reason from onInvalid — it receives the text the field just dropped.
• Paste reports little. With addOnPaste, pieces that fail onValidate are dropped without onInvalid, and a paste that would cross max is refused whole. When rejects must be listed, take paste over, as the recipients demo does.
• required is not enforced. It lands on the hidden input, and browsers never validate hidden inputs. Check value.length before you submit.
• readOnly leaves the ✕ looking live. The buttons look exactly as they do in an editable field, and pressing them does nothing. For a read-only view, render the tags as Badges.

Related

• Combobox and MultiCombobox — when the values come from a fixed list (projects, people, statuses) rather than free entry. Their search also ignores Vietnamese accents.
• Mention — people named inside running text, rather than as a separate list of tags.
• Badge Overflow — showing the saved tags in a table cell or card, collapsing the rest into “+N”.
• Patterns where it belongs: Tasks (labels on a task), Email (recipients in the composer) and CRM (tags on a contact record).

Accessibility

Keyboard work happens in the text field. The table covers the default dir="ltr".

• The text field is a plain <input type="text">, labelled by TagsInputLabel through aria-labelledby and htmlFor. The field carries that aria-labelledby whether or not the label is rendered, so where a design has no visible label, keep the label and give it className="sr-only" rather than reaching for aria-label.
• Tags are not a listbox or a grid: they are text in the box, each followed by a <button type="button"> named by deleteLabel. Those buttons are out of the Tab order on purpose — Backspace and Delete do the job from the field — and a screen reader's browse mode reaches them.
• Focus is never dropped: removing a tag by ✕ or by keyboard, Clear, and saving an edit all put focus back in the text field, and clicking empty space in the box focuses it too.
• At most, the component marks a refusal with data-invalid — and not even that at the limit. The app sets aria-invalid, points aria-describedby at the reason and puts that reason in a live region — the recipients demo does all three, with a -ink red border that stays red on hover and focus.
• In a <form>: with name, a hidden input posts the tags as JSON. Enter with text in the field commits a tag and never submits; Enter in an empty field submits like any text input. required does nothing — validate the count yourself.
• The highlighted tag is bg-accent with text-accent-foreground, the same pair as a highlighted command-menu row. A tag's border is decorative (--border): the control is the ✕, not the tag.
• Still yours: a label (visible, or sr-only), a hint that says how to add (“Enter or a comma”), the reason for every refusal, a name on an icon-only TagsInputClear, and the lang attribute on <html>.
• The field — and so the text typed into it — is 16px below md and 14px from md up, like every field since 3.13.4; the tags themselves stay 14px. Leave the size to the package; Input explains why.