Component

Combobox

Searchable single-selection dropdown (wraps Base UI Combobox).

Basic

No results

Type a query with no matches (e.g. "xyz") to see the built-in empty state.

Controlled

Selected: Apple

When to use

A single selection from a list long or unfamiliar enough that typing to filter is faster than scrolling.
Async or large option sets where you'd otherwise need a custom search UI.

When not to use

A short, fixed list (under ~10 items) - a plain Select is fewer keystrokes and simpler to scan.
Multiple selections - use MultiSelect, which has its own chip-based value model.
Free-text entry that isn't really a selection from a list - use Input instead.

Keyboard

Key	Action
Type	Filters the list by substring match against each item's label (case-insensitive).
ArrowUp / ArrowDown	Moves the highlighted item.
Enter	Selects the highlighted item and closes the popup.
Escape	Closes the popup without changing the value.
Backspace on an empty input with a value selected	Clears the current selection.

Mobile behavior

Opens the on-screen keyboard immediately on tap, same as a text input - there's no separate "open" step on touch.
The popup is width-matched to the trigger and viewport-clamped, so it doesn't overflow narrow screens.

Accessibility notes

Base UI wires role="combobox" on the input with aria-expanded and aria-activedescendant tracking the highlighted item.
The empty state ("No results found.") is rendered in the list region so it's discoverable by screen reader users navigating the popup, not just sighted users.

Common mistakes

Forgetting aria-label when there's no visible <label> - the input then announces as an unlabeled text box.
Expecting item-level disabled to work - it isn't currently supported on Combobox items (Select does support it; see Select for that case).
Filtering the items array yourself on every keystroke - Base UI already filters by label internally, so a custom filter usually just fights it.

Known limitations

Individual items don't currently support a disabled flag (Select and MultiSelect do).
Filtering matches item label substrings only - there's no built-in fuzzy or multi-field search.

Related components

Select Multi Select

Combobox props

Prop	Type	Default	Description
items	{ label: string; value: string }[]	None	The full option list - Base UI filters it internally as the user types.
value / onValueChange	ComboboxItem \| null	None	Controlled selected item.
placeholder	string	"Search…"	Input placeholder text.
invalid	boolean	false	Applies the invalid visual/aria state.

itemsNone

{ label: string; value: string }[]

The full option list - Base UI filters it internally as the user types.

value / onValueChangeNone

ComboboxItem | null

Controlled selected item.

placeholder"Search…"

string

Input placeholder text.

invalidfalse

boolean

Applies the invalid visual/aria state.

Criterion	Status	Note
Keyboard support	Supported	Type-to-filter, arrow-key highlight, Enter to select, Escape to close.
Focus management	Supported	Focus stays on the input the whole time; the popup never steals it.
Screen reader labels	Partial	Requires an explicit aria-label or <label> - not automatic.
Reduced motion	Supported	prefers-reduced-motion: reduce zeroes all Fuji transition durations globally.
Reduced transparency	Supported	prefers-reduced-transparency: reduce flattens Glass to opaque surfaces (portals included).
RTL layout	Partial	Logical flex/grid gap works under dir="rtl"; directional chevrons are not yet mirrored.

API reference

Prop	Type	Default	Description
items	option data	None	Searchable options.
value / defaultValue	string	None	Controlled or initial selection.
onValueChange	(value) => void	None	Called when an option is selected.
className	string	None	Additional classes applied to the component root.

itemsNone

option data

Searchable options.

value / defaultValueNone

string

Controlled or initial selection.

onValueChangeNone

(value) => void

Called when an option is selected.

classNameNone

string

Additional classes applied to the component root.