Loading navigation…
User
API and Development
Combobox provides a searchable popover for single-select (CommandList children) or multi-select (multiSelect with flat options). Shared props cover labels, search, loading, segmented filters, and open state. See Usage for when multiSelect applies versus NavigableMenu in menus.
| Name | Type | Default | Description |
|---|---|---|---|
label | string | required | Text on the trigger; in multi-select, this is the field title above pills. |
labelIcon | SVGAsset | — | Icon beside the label. |
prefix | ReactNode | — | Content before the trigger label (e.g. preview). Single-select oriented; omit when redundant with multi-select pills. |
searchable | boolean | true | Hide inline search when false (small lists). |
searchPlaceholder | string | "Search..." | Search input placeholder. |
emptyText | string | — | Copy when no options match the filter. |
searchValue | string | — | Controlled search text for server-side filtering; pair with onSearchChange. |
onSearchChange | (value: string) => void | — | Controlled search callback. |
loading | boolean | false | Loading spinner on the trigger. |
resultsLoading | boolean | — | Loading state inside the dropdown results region. |
disabled | boolean | false | Disables the trigger. |
required | boolean | false | Sets aria-required on the role="combobox" control (same contract as Input—not native required). Multi-select also renders a Label with a visual asterisk. Single-select does not—pair with an external Label required for the sighted indicator (label on the trigger is selected-value text, not a field title). |
segmentedControlItems | { value, label }[] | — | Optional segmented filter above the list (single-select content path). |
segmentedControlValue | string | — | Active segmented tab value. |
onSegmentedControlChange | (value: string) => void | — | Segmented tab change handler. |
open | boolean | — | Controlled popover open state. |
onOpenChange | (open: boolean) => void | — | Popover visibility callback. |
multiSelect | boolean | false | Wrapping chips field with inline search and highlighted option rows (trailing checkbox); requires options, does not render option children. |
options | ComboboxOption[] | [] | Flat { value, label, tooltip?, keywords?, disabled? } rows used only when multiSelect is true. Optional tooltip (ReactNode) is short option help: announced via aria-describedby, shown visually from the info icon on hover—not a second keyboard focus target. |
selectedValues | string[] | — | Controlled selected values (multi-select). |
defaultSelectedValues | string[] | [] | Initial selections when uncontrolled (multi-select). |
onSelectedValuesChange | (values: string[]) => void | — | Fires when selections change (multi-select). |
children | ReactNode | — | Single-select: Required dropdown body (CommandList/CommandItem). Ignored when multiSelect is true. |
data-test-id | string | — | Test selector on the container. |
Mirrors the Storybook default: selecting a person updates the trigger label.
Flat options, dismissible pills in a wrapping chips field, inline search, and highlighted option rows with trailing checkboxes. Use for multi-value form fields; for checklists inside menus, see NavigableMenu on Menu.
Selected pills and the inline search input share one wrapping surface that grows vertically up to three rows. The search field always retains at least two-thirds of the Combobox width. There is no chevron. The options panel includes Clear (resets selection, stays open) and Close footer actions whose background matches the overlay panel. Toggle options to change selection, dismiss pills, or press Backspace/Delete on an empty search input to remove the most recently selected value first (overflow / +N more entries before pills still visible in the field). When selections no longer fit those three rows while preserving the search width (and space for the overflow summary), trailing selections automatically collapse into a +N more pill that opens a checkbox Menu of the hidden values. The overflow menu and the options popover are mutually exclusive. There is no public opt-in or opt-out prop—overflow applies to every multiSelect Combobox. Dismissing a visible pill, pressing Backspace in an empty search input, or toggling overflow checkboxes recalculates fit; when all remaining selections fit, the overflow menu disappears and normal dismissible pills return. If overflow collapses while that menu is open, focus returns to the search input.
Use for searchable selection from a list of options with a simple interface.
Leverage the built-in search functionality to help users find options quickly.
Show loading indicators while options are being fetched or processed.
Enhance options with icons and additional visual elements for better user experience.
Prevent interaction when the combobox should not be accessible.
Organize options into logical groups (single-select path with CommandGroup). Multi-select does not consume grouped children.
Uses multiSelect, options, and controlled selectedValues / onSelectedValuesChange. Omit children. Option rows highlight on hover/keyboard and show a trailing checkbox.