Combobox
An autocomplete dropdown with single and multiple selection, chips, grouped collections, custom rows, keyboard navigation, and RTL — dependency-free.
Installation#
pnpm dlx shadcn@latest add @davinciui/comboboxUsage#
Composition
One control, composed through props. The text field, chips, clear button, popup, groups, and custom rows are all facets of the same component — no compound imports to wire.
Simple#
With chips#
With groups and collection#
Custom Items#
Multiple Selection#
Basic#
Multiple#
Clear Button#
Groups#
Invalid#
Disabled#
Auto Highlight#
Popup#
Input Group#
RTL#
API Reference#
| Prop | Type | Default |
|---|---|---|
itemsFlat options. Ignored when groups is provided. | ComboboxItem[] | — |
groupsGrouped options with label headers. | ComboboxGroup[] | — |
multipleMulti-select with chips. | boolean | false |
valueControlled selection. | string | string[] | null | — |
defaultValueUncontrolled initial selection. | string | string[] | null | null |
onValueChangeFires on every selection change. | (value) => void | — |
inputValueControlled filter text. | string | — |
defaultInputValueUncontrolled initial filter text. | string | "" |
onInputChangeFires when the filter text changes. | (value: string) => void | — |
openControlled popup state. | boolean | — |
defaultOpenUncontrolled initial popup state. | boolean | false |
onOpenChangeFires when the popup opens or closes. | (open: boolean) => void | — |
maxSelectionsCap for multiple mode. | number | — |
placeholderInput placeholder. | string | "Select…" |
emptyMessageContent for empty filter results. | React.ReactNode | "No results found." |
disabledDisable the whole control. | boolean | false |
invalidError state with aria-invalid. | boolean | false |
showClearButtonInline X that clears the selection. | boolean | false |
autoHighlightHighlight the first match on open/type. | boolean | false |
filterItemsCustom filter; defaults to contains-match. | (items, query) => ComboboxItem[] | — |
renderItemCustom option renderer. | (item, { selected, highlighted }) => ReactNode | — |
dirText direction. | "ltr" | "rtl" | "ltr" |
classNameExtra classes for the root. | string | — |
inputClassNameExtra classes for the text input. | string | — |
Accessibility#
The text input uses role='combobox' with aria-expanded, aria-controls, aria-activedescendant, and aria-autocomplete='list'; the popup is a listbox of options. Arrow keys, Home, End, Enter, Escape, and Backspace work. The input has no label prop, so the placeholder is the only accessible name.
Motion#
The popup opens and closes instantly with no animation; only the control border, chips, and icons use short CSS color transitions. prefers-reduced-motion is not queried because no motion is present.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

