Loading navigation…
User
Usage
Combobox pairs a field-style trigger with search and a list of options. It runs in two modes:
Single-select (default) uses children (CommandList, CommandItem) with typeahead toward one value. The mental model is "search, then pick one"—not free-form text outside the option list.
multiSelect is a deliberately narrow API: flat options (value, label, optional keywords), a wrapping chips field with an inline search input, highlighted option rows with trailing checkboxes, and a Clear/Close footer. It exists for filter-bar or form facets—homogeneous searchable lists whose values should stay visible as chips when closed. General-purpose menus, nested structures, or mixed actions are out of scope; use NavigableMenu with checkboxes there.
Dispatch-style single-select stays the common case—agency switchers, incident filters, language, transfer targets. Multi-select fits the subset of workflows where operators pick many homogeneous tags or facet values and need chips without building a bespoke pattern elsewhere.
Call queue
CommandList / CommandItem).keywords.multiSelect + flat options (facets, tags), not mixed overflow menus.People, agencies, incident types, tags, talkgroups. Anywhere the set is too long to scan and typing narrows results faster than scrolling. When the list is paginated or backed by a live query, combobox matches a keyboard-first workflow.
Beyond the visible label via keywords. "Eng" matches "Engine"; a CAD code matches a friendly name.
Single-select with CommandGroup when operators should not need to know the category to find an item.
Enable multiSelect when:
If trigger is contextual ("⋯" on a row) or the dropdown mixes verbs, separators, nesting, checkboxes together, use NavigableMenu searchable + MenuItemCheckbox instead.
NavigableMenu with searchable / MenuItemCheckbox instead of Combobox multiSelect.Select.Input or create flows.Command.Prefer NavigableMenu if the UI is toolbar overflow, card or row menus, nested panes, or a single dropdown that combines plain items, separators, radios, switches, and checkboxes. Combobox multiSelect is not a substitute for command menus—it is a options-driven picker with a labeled chips-field affordance.
Prefer Select. Typeahead rarely pays off on tiny lists.
If values may fall outside the list, use Input or a create-allowed pattern—not the combobox contract.
Use Command. Combobox binds to one or many discrete option keys; Command runs actions.
Prefer Combobox multiSelect | Prefer NavigableMenu + searchable + MenuItemCheckbox |
|---|---|
| Labeled filter or form row; wrapping chips field when closed | Icon or overflow trigger; dismiss after tweaks; often no pills on trigger |
One homogeneous option shape and options array | children: heterogeneous items and nested submenus |
| Inline search, chip dismiss, and list toggles that keep the popup open | Checkbox toggles scattered among other menu items |
| Aspect | Purpose | Emphasis |
|---|---|---|
Label (and optional labelIcon, single-trigger) | Field identity | Never replace readable label text with icon-only chrome |
Search vs. searchable={false} | Short lists (e.g. ≤4 rows) hide search | Prefer still supplying a visible field label |
multiSelect chips field | Many values with inline search and removable pills | Search always retains at least two-thirds of the field width; localize the automatic +N more overflow summary |
multiSelect pill overflow | Collapse selections that do not fit three wrapped rows into +N more | Overflow is automatic—no opt-in prop; prefer short pill labels so more values stay visible |
| Command groups (single-select) | Sections in long lists | Shallow grouping only |
| Empty / loading copy | Guided recovery | Actionable empties; visible loading |
Single-select. Trigger shows chosen label or placeholder; panel has search plus CommandList / CommandItem. Keep trigger text aligned with onSelect state.
multiSelect. No CommandItem children—pass options, selectedValues / onSelectedValuesChange (or uncontrolled defaultSelectedValues). The trigger is one wrapping chips surface: dismissible pills, optional +N more, and an inline search input that always retains at least two-thirds of the field width. The field grows naturally from one to three rows. When pills would reduce the search area or exceed those three rows, trailing values collapse into a +N more pill that opens a checkbox Menu of the hidden values. There is no chevron; the options panel includes Clear (reset selection, stay open) and Close footer actions.
Single-select: options as CommandItem (+ optional keywords). Multi-select: options only; same keyword behavior for narrowing.
Suggest what to change in empty states. Avoid twitchy loading on the trigger—keep it perceptible enough to read.
formatMessage, sentence case where product allows.CommandItem children when needed (single-select).multiSelect). Use options[].tooltip for short help text. Do not rely on the info icon as a keyboard affordance—screen readers get the description via aria-describedby.+N more checkbox menu.multiSelect: pills and inline search share one wrapping chips field that grows vertically (up to three rows), while search retains at least two-thirds of the field width. Leading pills that fit stay dismissible; remaining selections collapse into +N more. Backspace or Delete in an empty search input removes the most recently selected value first (overflow entries before visible pills).Escape to close without stray commits.multiSelect). Arrow keys move the highlight; Enter or click toggles selection without closing; selected rows show a trailing checkbox; Escape closes and keeps focus on the search input.+N more opens a checkbox menu of the currently hidden selections and closes the Combobox options popover if it was open (and the reverse when the options popover opens). The menu snapshots those items when opened so operators can uncheck and recheck during that session. Removing enough values (from the menu or by dismissing an earlier pill) recalculates fit across three rows and returns to normal dismissible pills when everything fits; if the overflow menu was open, focus returns to the search input.Do
multiSelect only along with the homogeneous options model and chips-on-close requirement.Don't
multiSelect as "MenuItemCheckbox plus search" inside arbitrary menus—it is intentionally separate.Enter.Accessibility covers single-select listbox typeahead, multiSelect chips-field keyboard navigation with highlighted rows, and keyboard/focus expectations for the +N more overflow menu.
NavigableMenu for searchable checklists merged with actions or nesting—not the combobox multiSelect shape.On this page