Combobox
Last Updated: September 2026Comboboxes let users search and select from a list of options in a compact, filterable field.
Source CodeAnatomy
link- 1Input
- 2Content
- 3Item
- 4Empty
Variants
linkDefault
Inline combobox with input, list, and empty state.
Custom placeholder
Override the Input placeholder (default is “Search”).
With descriptions
Secondary line via Combobox.Item.Description.
Empty state
Type a query that matches nothing to see Combobox.Empty.
Usage Guidelines
linkWhen to use
- •When users need to search or filter a list of options while selecting.
- •For longer option sets where a plain Select becomes hard to scan.
- •Inside popovers or modals for compact picker UIs.
When not to use
- •For short fixed lists — prefer Select.
- •For free-form text without a known option set — use Input.
- •For multi-filter chips — combine Chip with a menu pattern.
Pass a stable items array and render each row from Combobox.Content.
Don't use Select for long searchable lists — prefer Combobox.
Always include Combobox.Empty so filtered-out queries aren’t a blank panel.
Don't omit Empty — users get no feedback when search returns nothing.
Behaviors
linkAlways open / inline
- •Root forces open and inline — this Combobox is an embedded search list, not a closed dropdown.
- •Host it in a sized container, Popover, or Modal (see stories).
Value model
- •Pass items to the root; Content receives each item via a render function.
- •Uncontrolled: defaultValue; controlled: value + onValueChange.
Compound parts
- •Combobox.Input, Content, Item, Empty.
- •Combobox.Item.Description for optional secondary text (slot via useSlots).
Content Guidelines
linkItems
- •Keep labels scannable; put extra detail in Description.
- •Use stable value ids — not display strings — for form state.
Empty copy
- •Empty should say what failed (“No departments match”), not only “No results”.
Accessibility
linkText & Labels
- •Customize Input placeholder to describe the choice when context isn’t obvious.
- •Item labels should be unique enough to distinguish rows.
ARIA attributes
- •Built on Base UI Combobox — listbox semantics with filterable input.
- •Highlighted items follow pointer and keyboard focus.
Keyboard Support
- •Type in the input to filter.
- •Arrow keys move highlight among items.
- •Enter selects the highlighted item.
WCAG Compliance Standards
FAQs
linkWhy is the list always visible?
Root sets open and inline — designed for popovers/modals/panels, not a closed Select-style trigger.
How do I render items?
Pass items on the root and use Combobox.Content with a function child that returns Combobox.Item per item.
Combobox vs Select?
Select for short fixed lists; Combobox when users need to filter a longer set while choosing.