Form Inputs
ComboBox
A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.
A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.
Empty state#
When filtering returns no matches, the combo box displays a helpful empty state. Use emptyState
to replace it with custom content (renderEmptyState is still supported but deprecated).
Component props#
| Name | Type | Description |
|---|---|---|
| inputValue | string | Controlled input value |
| defaultInputValue | string | Default input value |
| selectedKey | string | Controlled selected key |
| defaultSelectedKey | string | Default selected key |
| isDisabled | boolean | Disables the combobox (disabled is also accepted) |
| showClear | boolean | Shows a clear button while the input has a value |
| showIcon | boolean | Shows the open/close trigger button (default: true) |
| aria-invalid | boolean | Marks the input as invalid |
| onInputChange | (value: string) => void | Called when input changes |
| onSelectionChange | (key: string) => void | Called when selection changes |
| emptyState | ReactNode | Replaces the default empty-state message |
| renderEmptyState | Function | Deprecated alias for emptyState |
| itemToStringLabel | (item) => string | Resolves the display label for an item |
| itemToStringValue | (item) => string | Resolves the form value for an item |
Anatomy#
Items are handed to Base UI as { label, value } objects, so filtering and label resolution happen
inside the primitive. The rendered parts expose data-slot attributes: combobox,
combobox-input, combobox-clear, combobox-trigger, combobox-positioner, combobox-content,
and combobox-empty.