Component

Combobox

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

Basic

Sizes

sm / md / lg, matching Input and Button heights.

States

Disabled and invalid. disabled dims the whole field, toggle included, and blocks input.

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 does).
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 *	ComboboxItem[]	None	Options to render.
aria-label	string	None	Accessible name for the search input. Required when there is no visible `<label>` for this combobox.
aria-labelledby	string	None	Points at an existing visible label's id, as an alternative to `aria-label`.
className	string	None	Extra classes merged onto the input.
invalid	boolean	None	Paints the error state. Pair with `FormField`'s `error` for the message.
placeholder	string	"Search…"	Text shown while nothing is selected.
size	ComponentSize	"md"	Control height, matching `Input` and `Button` at the same size.

items *None

ComboboxItem[]

Options to render.

aria-labelNone

string

Accessible name for the search input. Required when there is no visible `<label>` for this combobox.

aria-labelledbyNone

string

Points at an existing visible label's id, as an alternative to `aria-label`.

classNameNone

string

Extra classes merged onto the input.

invalidNone

boolean

Paints the error state. Pair with `FormField`'s `error` for the message.

placeholder"Search…"

string

Text shown while nothing is selected.

size"md"

ComponentSize

Control height, matching `Input` and `Button` at the same size.

Also accepts everything from Omit<React.ComponentPropsWithoutRef<typeof import("@base-ui/react/combobox").Combobox.Root<ComboboxItem, false>>, "items" | "multiple">.

Coding agents read this reference, with its examples, from the version your project has installed, through the Fuji UI MCP server. Set up your agent