Tag Combobox

ProNew

An accessible multi-select combobox with typeahead, inline chips, grouped and disabled options, create-on-type, limits and native form submission.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tag-combobox

Usage

Examples

Large lists, limits and errors

Over 250 countries, matched by name, native name, capital and ISO code. Only the first 40 results render, with a "Show more" row, so long lists stay fast. maxSelected disables the rest once the limit is reached, and invalid shows the error state.

Open in

With react-hook-form

TagCombobox reads id, aria-invalid and aria-describedby from shadcn/ui's FormControl and puts them on the input, so it drops into a FormField:

Props

Prop	Type	Default	Description
`options`	`TagComboboxOption[]`	-	Every option. See below.
`value`	`string[]`	-	Selected values when controlled.
`defaultValue`	`string[]`	`[]`	Selected values when uncontrolled.
`onValueChange`	`(value: string[]) => void`	-	Called with the full selection.
`placeholder`	`string`	`"Search…"`	Shown while nothing is selected or typed.
`creatable`	`boolean`	`false`	Offer a "Create" row for unmatched text.
`onCreate`	`(label) => TagComboboxOption \| void`	-	Build the created option. Without it, the text is value and label.
`maxSelected`	`number`	-	Selection limit; shows a counter and disables the rest.
`loading`	`boolean`	`false`	Spinner row for async options.
`onSearchChange`	`(search: string) => void`	-	Called as the person types, for server-side filtering.
`emptyMessage`	`ReactNode`	`"No results"`	Shown when nothing matches.
`renderLimit`	`number`	`60`	Results rendered before the "Show more" row.
`name`	`string`	-	Submits each value as a hidden input with this name.
`invalid`	`boolean`	-	Error styling and `aria-invalid`.
`disabled`	`boolean`	`false`	Disables the field.
`inputId`	`string`	-	id of the text input, for `<label htmlFor>`.
`inputRef`	`Ref<HTMLInputElement>`	-	Ref to the text input.
`onBlur`	`() => void`	-	Called when focus leaves the field.

TagComboboxOption

Field	Type	Description
`value`	`string`	Stored value.
`label`	`string`	Visible text, matched while typing.
`group`	`string`	Group heading (hidden while searching).
`disabled`	`boolean`	Visible but not selectable.
`color`	`string`	Any CSS colour for the dot, such as a token.
`keywords`	`string[]`	Extra matches, such as codes or aliases.
`icon`	`ReactNode`	Leading visual.

Accessibility

Follows the WAI-ARIA APG combobox pattern with a listbox popup:

The input has role="combobox", aria-expanded, aria-controls and aria-activedescendant. Focus stays in the input while Arrow Up and Arrow Down move through options, skipping disabled ones.
The listbox is aria-multiselectable; options expose aria-selected and aria-disabled, and group headings label their group.
Enter toggles the active option, Escape closes the list (or clears the text), Backspace in an empty input removes the last chip.
Arrow Left at the start of the input moves into the chips; Arrow Left and Right move between them, Delete or Backspace removes the focused chip, and Arrow Right past the last chip returns to the input.
Selections, removals and the limit are announced in a polite live region.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/tag-combobox

Usage