TagsInput

A multi-value text input that turns typed text, pasted strings, and optional suggestions into an array of string tags. Companion to <MultiCombobox>:

Both render badge chips inside a form-control shell, but the data flows are different. Pick the one that matches the UX intent.

Why this exists

Hand-rolling a chips-input gets ten things wrong:

• ❌ Press Enter on the last tag and the form submits.
• ❌ Backspace deletes a tag without warning.
• ❌ Paste a CSV of emails — it lands as one giant tag.
• ❌ No keyboard way to remove a tag once you're past it.
• ❌ Screen readers hear "removable" buttons but no announcement when you actually remove one.
• ❌ Suggestions overlay never opens on small windows because of overflow.
• ❌ Validation lives in the consumer and the field looks fine while it's wrong.

<TagsInput> ships every one of those fixed: a role="combobox" input with the W3C tags-input keyboard contract (commit/remove/tag-cursor), per-tag validate() that surfaces both visually (danger Badge color, title tooltip) and audibly (live-region announcement), paste-aware splitOn, optional maxTags enforcement, hidden inputs for native form submission, and an inline suggestion listbox that doesn't fight the page.

Anatomy

┌────────────────────────────────────────────────────────────┐
│  Tags *                                ← label              │
│  ─────────────────────────────────────────────              │
│  ╔════╗ ╔════╗ ╔════╗  type here…  3 / 10  ← field          │
│  ╚════╝ ╚════╝ ╚════╝                                       │
│  ─────────────────────────────────────────────              │
│  ┌───────────────────────────────────┐  ← suggestions       │
│  │ TypeScript                        │     listbox          │
│  │ TypeORM                           │     (inline)         │
│  └───────────────────────────────────┘                      │
│  Add at least one tag                  ← helper / error     │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│  Tags *                                ← label              │
│  ─────────────────────────────────────────────              │
│  ╔════╗ ╔════╗ ╔════╗  type here…  3 / 10  ← field          │
│  ╚════╝ ╚════╝ ╚════╝                                       │
│  ─────────────────────────────────────────────              │
│  ┌───────────────────────────────────┐  ← suggestions       │
│  │ TypeScript                        │     listbox          │
│  │ TypeORM                           │     (inline)         │
│  └───────────────────────────────────┘                      │
│  Add at least one tag                  ← helper / error     │
└────────────────────────────────────────────────────────────┘

• field — role="group" chip-row. Click anywhere → focuses the input.
• input — role="combobox" with aria-expanded / aria-controls / aria-activedescendant.
• tag chip — <Badge removable> by default; replace via renderTag.
• suggestions — inline role="listbox" below the field; auto-opens when typing matches.
• live region — off-screen aria-live="polite" that announces add / remove / invalid / duplicate.

Examples

Props

Keyboard

A11y

• input is role="combobox", aria-autocomplete="list", aria-expanded, aria-controls, aria-activedescendant — standard ARIA combobox pattern.
• field is role="group"; clicking it focuses the input.
• Tag chips are <span> by default (decorative); the remove button inside each chip is the actionable element with aria-label="Remove {tag}".
• Live region (aria-live="polite") announces 'Added tag …' / 'Removed tag …' / '{tag} is already added' / 'Maximum N tags reached' / '{tag}: {error}'.
• useFormFieldA11y (shared with <Input>, <Textarea>, <Select>, <Combobox>) wires label / description / helper / error IDs into aria-labelledby + aria-describedby.
• axe-core: 0 violations in basic / labeled / max-reached / disabled / error / suggestion-open modes.

RTL

• The chip row's flex-wrap mirrors natively under dir="rtl".
• Arrow key semantics flip: ArrowRight activates the cursor in RTL.
• Hidden input order matches the visual tag order (last-typed = last in value = last <input>).

Theming

<TagsInput> registers with the theme as TagsInput. Slot names:

wrapper · label · description · field · input · count · emptyHint · listbox · item · empty · helperText

const theme = createTheme({
  components: {
    TagsInput: {
      defaultProps: { variant: 'filled', tagColor: 'primary' },
      styleOverrides: {
        field: 'gap-2 min-h-12',
        item: 'data-[active=true]:bg-primary/10',
      },
    },
  },
});

const theme = createTheme({
  components: {
    TagsInput: {
      defaultProps: { variant: 'filled', tagColor: 'primary' },
      styleOverrides: {
        field: 'gap-2 min-h-12',
        item: 'data-[active=true]:bg-primary/10',
      },
    },
  },
});

See also

• <MultiCombobox> — constrained-list multi-select (every value must come from an option).
• <Combobox> — single-value searchable select.
• <Badge> — the chip primitive used for default tag rendering.
• <Input> / <Textarea> — single-value text controls; same form-field surface.