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.
Reset zoom to 100%
When to use
Typeahead single-select for long or server-backed lists (CommandList / CommandItem).
Synonym and code matching via keywords.
Multi-value only as a labeled field with chips: multiSelect + flat options (facets, tags), not mixed overflow menus.
For long or dynamic single-select lists
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.
For keyword matching on synonyms or codes
Beyond the visible label via keywords. "Eng" matches "Engine"; a CAD code matches a friendly name.
For grouped options where search spans groups
Single-select with CommandGroup when operators should not need to know the category to find an item.
For multi-select only when it looks like a field, not an overflow menu
Enable multiSelect when:
Selection is the persisted filter or field state.
Rows are uniform (label + trailing checkbox, optional keywords)—no custom mix of actions, radios, and submenus in the same overlay.
The closed control should show removable pills in a wrapping chips field so operators confirm many values without reopening.
If trigger is contextual ("⋯" on a row) or the dropdown mixes verbs, separators, nesting, checkboxes together, use NavigableMenusearchable + MenuItemCheckbox instead.
When not to use
Heterogeneous menus (actions + checkboxes + submenus in one surface)—use NavigableMenu with searchable / MenuItemCheckbox instead of ComboboxmultiSelect.
Small static lists (fewer than about eight options)—prefer Select.
Values outside the option list—Input or create flows.
When multi-select overlap should be NavigableMenu, not Combobox
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. ComboboxmultiSelect is not a substitute for command menus—it is a options-driven picker with a labeled chips-field affordance.
For a small fixed set (roughly fewer than eight)
Prefer Select. Typeahead rarely pays off on tiny lists.
For free-form entry
If values may fall outside the list, use Input or a create-allowed pattern—not the combobox contract.
For command palettes or action launchers
Use Menu. Combobox binds to one or many discrete option keys; Menu runs actions.
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
Variants
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
Composition
Single-select. Trigger shows chosen label or placeholder; panel has search plus CommandList / CommandItem. Keep trigger text aligned with onSelect state.
multiSelect. No CommandItemchildren—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.
Options and keywords
Single-select: options as CommandItem (+ optional keywords). Multi-select:options only; same keyword behavior for narrowing.
Empty and loading
Suggest what to change in empty states. Avoid twitchy loading on the trigger—keep it perceptible enough to read.
Content guidelines
Labels.formatMessage, sentence case where product allows.
Options. Concise rows; richer copy in CommandItem children when needed (single-select).
Option tooltips (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.
Keywords. Operators’ shorthand, codes, synonyms.
Truncation. Expose full text to assistive tech when truncated in trigger or pills. Overflowed multi-select pills remain available through the +N more checkbox menu.
Behavior and states
Closed. Single-select: chosen label or placeholder. 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).
Open — single-select. Arrow + Enter semantics; Escape to close without stray commits.
Open — multi-select (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.
Overflow menu. Clicking +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.
Loading / disabled. Do not pretend stale data is current; respect disabled/tab order conventions.
Best practices
Do
Debounce costly search; prefer server-backed filters for huge sets.
Use multiSelect only along with the homogeneous options model and chips-on-close requirement.
Don't
Treat multiSelect as "MenuItemCheckbox plus search" inside arbitrary menus—it is intentionally separate.
Auto-commit single-select on first typed character—confirm with Enter.
Tunnel keyboard traps into the panel without testing both modes.
Accessibility
Accessibility covers single-select listbox typeahead, multiSelect chips-field keyboard navigation with highlighted rows, and keyboard/focus expectations for the +N more overflow menu.
Related Components
Menu: NavigableMenu for searchable checklists merged with actions or nesting—not the combobox multiSelect shape.