Skip to content
uiify

Framework

Next.jsTanStack StartAstroVike

Style

CSSTailwind

Theme

Language

English简体中文日本語العربيةРусскийEspañolPortuguês (Brasil)Pseudo (accented)Pseudo (bidi)

Combobox

Single- or multi-value ARIA combobox with filtering.

Browsers
Chrome 114+Firefox 125+Safari 17+
Tier
2
Bundle compressed
5.18 kB
Forced layout budget
0 ms
Axe budget
0
SSR compatible
Yes
Published contract
Test harness

Playground

Combobox

Default

Apple
Banana
Cherry
Date

Multiple

ReactUI
React
UI
TypeScript
Accessibility
Design systems

Open

Apple
Banana
Cherry
Date

Large

API

Combobox.Root

PropTypeDefaultDescription
childrenReactNode—Combobox parts: control, tags, input, trigger and content.
items*ComboboxItemData[]—Full list of options the input filters over.
defaultInputValuestring—Starting text in the input when the input value is uncontrolled.
defaultOpenboolean—Whether the list starts open when the open state is uncontrolled.
defaultValuestring | readonly string[]—Value or values selected on first render when the selection is uncontrolled.
multiplebooleanfalseAllows selecting and removing multiple values as tags.
allowCustomValuebooleanfalseAllows typed text that is not in items to become a selected value.
addOnPastebooleantrueAdds multiple delimited values from pasted text in multiple mode.
delimitersreadonly string[][","]Characters that commit or split typed values in multiple mode.
maxValuesnumber—Largest number of values that can be selected in multiple mode.
validateValue(value: string) => boolean—Rejects a custom value when it returns false.
filterFn(items: ComboboxItemData[], inputValue: string) => ComboboxItemData[]—Replaces the built-in filter that narrows items as the user types.
inputValuestring—Text in the input, making the typed value controlled.
onInputValueChange(value: string) => void—Called with the new text whenever the input changes.
onOpenChange(open: boolean, details: OpenChangeDetails) => void—Called when the list opens or closes, with the reason for the change.
onValueChange((value: string) => void) | ((value: string[]) => void)—Called with the selected value or full selected-values array.
openboolean—Whether the list is open, making the open state controlled.
valuestring | readonly string[]—Selected value or values, making the selection controlled.

Combobox.Control

PropTypeDefaultDescription
childrenReactNode—Tags and input rendered inside the shared visual control.
classNamestring—Class applied to the control element.
renderReactElement | ((props, state) => ReactElement)—Replace the rendered element while keeping behavior and accessibility wiring.

Combobox.Tags

PropTypeDefaultDescription
childrenReactNode—Content appended after the generated removable tags.
classNamestring—Class applied to the generated tags container.
renderReactElement | ((props, state) => ReactElement)—Replace the rendered element while keeping behavior and accessibility wiring.

Combobox.Input

PropTypeDefaultDescription
classNamestring—Class applied to the text input.
renderReactElement | ((props, state) => ReactElement)—Replace the rendered element while keeping behavior and accessibility wiring.

Combobox.Trigger

PropTypeDefaultDescription
childrenReactNode—Content of the button that opens the list, such as an icon.
classNamestring—Class applied to the trigger button.
renderReactElement | ((props, state) => ReactElement)—Replace the rendered element while keeping behavior and accessibility wiring.

Combobox.Content

PropTypeDefaultDescription
align"start" | "center" | "end"—Alignment of the list against the input along the chosen side.
children*(filteredItems: ComboboxItemData[]) => ReactNode—Render function called with the items left after filtering.
classNamestring—Class applied to the list popup.
side"top" | "right" | "bottom" | "left"—Side of the input the list is placed on.

Combobox.Item

PropTypeDefaultDescription
classNamestring—Class applied to the option element.
item*ComboboxItemData—The item this option renders, normally taken from the content callback.

Combobox.Empty

PropTypeDefaultDescription
childrenReactNode—Content shown when filtering leaves no items.
classNamestring—Class applied to the empty-state element.

ComboboxItemData

PropTypeDefaultDescription
disabledboolean—Makes this item unselectable.
label*string—Text shown for the item and matched by the filter.
value*string—Value reported when the item is selected.

Keyboard

KeyAction
↓ / ↑Open and rove options
EnterSelect
EscapeClose
a–zTypeahead to filter options

Accessibility

ARIA combobox + listbox. Active option is announced via aria-activedescendant. Content exposes open/closed state; options expose highlighted, disabled and (in multiple mode) selected state. Use Empty to explain when no options match. Popup presence motion is disabled when reduced motion is preferred.

Styling hooks

data-statedata-highlighteddata-disableddata-selected