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
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Combobox parts: control, tags, input, trigger and content. |
items* | ComboboxItemData[] | — | Full list of options the input filters over. |
defaultInputValue | string | — | Starting text in the input when the input value is uncontrolled. |
defaultOpen | boolean | — | Whether the list starts open when the open state is uncontrolled. |
defaultValue | string | readonly string[] | — | Value or values selected on first render when the selection is uncontrolled. |
multiple | boolean | false | Allows selecting and removing multiple values as tags. |
allowCustomValue | boolean | false | Allows typed text that is not in items to become a selected value. |
addOnPaste | boolean | true | Adds multiple delimited values from pasted text in multiple mode. |
delimiters | readonly string[] | [","] | Characters that commit or split typed values in multiple mode. |
maxValues | number | — | 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. |
inputValue | string | — | 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. |
open | boolean | — | Whether the list is open, making the open state controlled. |
value | string | readonly string[] | — | Selected value or values, making the selection controlled. |
Combobox.Control
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Tags and input rendered inside the shared visual control. |
className | string | — | Class applied to the control element. |
render | ReactElement | ((props, state) => ReactElement) | — | Replace the rendered element while keeping behavior and accessibility wiring. |
Combobox.Tags
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Content appended after the generated removable tags. |
className | string | — | Class applied to the generated tags container. |
render | ReactElement | ((props, state) => ReactElement) | — | Replace the rendered element while keeping behavior and accessibility wiring. |
Combobox.Input
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | Class applied to the text input. |
render | ReactElement | ((props, state) => ReactElement) | — | Replace the rendered element while keeping behavior and accessibility wiring. |
Combobox.Trigger
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Content of the button that opens the list, such as an icon. |
className | string | — | Class applied to the trigger button. |
render | ReactElement | ((props, state) => ReactElement) | — | Replace the rendered element while keeping behavior and accessibility wiring. |
Combobox.Content
| Prop | Type | Default | Description |
|---|---|---|---|
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. |
className | string | — | Class applied to the list popup. |
side | "top" | "right" | "bottom" | "left" | — | Side of the input the list is placed on. |
Combobox.Item
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | Class applied to the option element. |
item* | ComboboxItemData | — | The item this option renders, normally taken from the content callback. |
Combobox.Empty
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Content shown when filtering leaves no items. |
className | string | — | Class applied to the empty-state element. |
ComboboxItemData
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean | — | 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
| Key | Action |
|---|---|
| ↓ / ↑ | Open and rove options |
| Enter | Select |
| Escape | Close |
| a–z | Typeahead 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