Skip to content

Design system

Documentation

DesignComponents / Combobox

Components / Combobox

Beta

Combobox

Search and select one or more supplied options with keyboard-operable list behavior.

On this page

Examples

Search local options

Type to filter a fixture list with the built-in matcher.

Searchable project owner picker

Choose multiple options

Keep selected option objects in feature state.

Multiple notification channel picker

Callback search

The application receives a debounced query and supplies the current result options.

Combobox callback search preview

When to use

Use Combobox when a person needs to search a known option set while keeping listbox keyboard behavior. Single values and multiple values are owned by the feature. For callback search, Combobox waits 350 ms by default, calls onSearch with the query, and leaves requests, race handling, loading/error state, and refreshed options to the application. The callback is not awaited and no request is made by the component.

Usage

import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxLabel,
ComboboxList,
} from "@phuctech/ui/components/combobox";

type Person = { value: string; label: string };
const people: Person[] = [{ value: "ava", label: "Ava Nguyen" }];

<Combobox items={people} onSearch={(query) => loadPeople(query)}>
<ComboboxLabel htmlFor="person-search">Person</ComboboxLabel>
<ComboboxInputGroup>
  <ComboboxInput id="person-search" placeholder="Search people" />
</ComboboxInputGroup>
<ComboboxContent>
  <ComboboxEmpty>No people found.</ComboboxEmpty>
  <ComboboxList>
    {(person: Person) => <ComboboxItem key={person.value} value={person}>{person.label}</ComboboxItem>}
  </ComboboxList>
</ComboboxContent>
</Combobox>

When onSearch is supplied, local filtering defaults off so the application can replace items or supply filteredItems. Search results remain fixture data in documentation examples; applications own network requests and stale-response protection.

API

Component API
PropTypeDefaultDescriptionConstraints
items / filteredItemsreadonly Item[]—Supplies selectable values and, optionally, the result list filtered by the feature.Use item objects shaped like { value, label } or provide itemToStringLabel and itemToStringValue.
value / defaultValue / onValueChangeItem | Item[] | null / callbackuncontrolled emptyControls single or multiple selection.With multiple, values are Item[]; selected state and persistence stay in the feature.
multiplebooleanfalseAllows more than one selected option.Pair with an array value when controlled.
onSearch(query: string) => void—Receives the trimmed query after the debounce window.No request is awaited. The application owns loading, errors, results, cancellation, and stale-response protection.
searchDebounceMsnumber350Sets the quiet period before onSearch runs.Clamped to 300–500 ms; identical consecutive queries are skipped.
filternull | (item, query, label) => booleanbuilt-in local filter; null with onSearchControls local filtering behavior.Use null when options already represent callback results.
inputValue / onInputValueChangestring / callbackuncontrolledControls typed text and receives input changes.The callback also includes Base UI event details.
disabled / readOnly / open / onOpenChangeBase UI Root propsenabled / editable / uncontrolledControls interaction and popup visibility.Base UI root props are forwarded.
Compound partsLabel, InputGroup, Input, Trigger, Clear, Content, List, Item, Empty, Status—Compose the accessible input and popup surface.Use ComboboxItem for every option; keep status and empty messages concise.

Tokens

Component tokens
TokenRoleEffective valueUsage
input / border / focus-ringSearch fieldShared form-control rolesComboboxInput reuses the Input class variants.
popover / elevation-popoverOption surfaceShared overlay rolesKeeps the list surface consistent with Select and Popover.
--size-control-* / --size-icon-*Trigger and option densityShared size scaleAligns clear, popup, and selection indicators with other controls.

Accessibility

  • Provide a visible ComboboxLabel connected to the input, or an explicit accessible name.
  • Base UI provides listbox keyboard navigation, option selection, and popup focus behavior; disabled options stay out of selection.
  • Use ComboboxStatus for externally owned loading or error messages and ComboboxEmpty for a settled empty list.
  • Do not rely on color alone to communicate selected, disabled, loading, or error states.

Do and don’t

Do

Debounce live search and update the option list from the feature that owns the request.

Don’t

Start a network request per keystroke or assume an older response is still current.

  • Select is a compact choice list for options that do not need a search input.
  • Field connects input labels and validation messages.