Combobox

Purpose

A searchable single-select dropdown — a button trigger that opens a filterable list. Use when a select would be too long to scan. For a few always-visible options use radio-group; for actions use dropdown-menu.

Anatomy

A composed component: a button trigger inside a popover, containing a command (cmdk) list. Options are passed as data (options: {value,label}[]).

Style

No variants — token-backed outline trigger + portalled command list. The popup matches the trigger width.

Behavior & functionality

• Controlled via value + onValueChange. Typing filters by label (cmdk keys on the option value; the label is added as a search keyword).
• Selecting the already-selected option toggles it off and emits "".
• Single-select only; for multi-select/chips, compose command directly.

Accessibility

• Trigger has role="combobox" + aria-expanded; the list is keyboard-navigable (arrows, Enter to select, Escape to close); focus returns to the trigger on close.
• Give the trigger an accessible name (label or aria-label).

Do / Don't

• ✅ Use for long/searchable single-select lists.
• ❌ Don't use for multi-select — compose command, or use a different control.