Forms

Combobox

Combobox is an editable searchable single-select with a filterable listbox — distinct from non-searchable Select and query-only Search Field.

State × Size — 15 variants (Figma); Beta React supports default, error, and disabled

betaReact AvailableFigma AvailableDocs Partial

React last updated: 2026-07-12
Documentation last updated: 2026-06-01
Accessibility target: WCAG 2.2 AA (target)
Version: 0.2.0-beta

Known open questions

Figma MCP inspection unavailable in parity pass — component-set node ID and exact token values remain unresolved.
Multi-select chips mode exists in Figma but is deferred in Beta.
Clear control not confirmed via MCP — deferred.
Option leading icons and descriptions not confirmed via MCP — deferred.
Remote/async fetching is not implemented.
Free-form custom values are not supported — closed predefined option list only.
Diacritic-insensitive filtering is not implemented — locale lowercase only.

Live preview

Combobox combines an editable text input with a filterable listbox. It chooses one predefined option — not free-form text, remote search, or multi-select.

Country (prefix filter)

Country

Filtering and keyboard selection

Team member (substring filter)

Assignee

Required, error, and disabled

States

Required country

Region

Choose a valid country.

Legacy country

Controlled value and input

Controlled

Project owner

Search label

Selected value: ca · Input text: Canada

Long result list

Many countries

Destination

Form submission

Submit canonical option value

Combobox inside Dialog

Combobox inside Drawer

Purpose

An editable single-select field that filters a predefined option list while typing — distinct from non-searchable Select and query-only Search Field.

Anatomy

Combobox = editable text input + filterable Popover listbox + hidden submitted value + FormField label/validation.

Variants and states

default · error · disabled

When to use

Long predefined option lists where typing to filter is faster than scrolling, such as countries, assignees, or project names.

When not to use

Short fixed lists with no search benefit — use Select. Free-text queries without option commitment — use Search Field.

Accessibility

Uses the editable combobox pattern: native text input with role="combobox", aria-autocomplete="list", aria-controls pointing to a listbox, aria-activedescendant for keyboard navigation while DOM focus stays in the input. Filter status uses a polite role="status" region — not role="option" for empty rows.

Keyboard behavior

Focus remains in the input. Arrow keys move aria-activedescendant. Enter commits the active option. Escape closes without clearing. Tab closes without implicit selection.

Common mistakes

Treating typed text as the submitted form value, moving DOM focus into options, or using role="dialog" on the popup shell.

Properties

State as variants. Value stores the committed option value; input text is editable for filtering. Multi-select chips exist in Figma but are deferred in Beta.

What is the difference between Combobox and Select?

Select uses a button-like combobox trigger with a non-editable display label. Combobox uses an editable input to filter predefined options.

What is the difference between Combobox and Search Field?

Search Field captures a query string. Combobox commits one predefined option value for forms and selection workflows.

Does Combobox allow custom values?

No in Beta. Unmatched blur text reverts to the last committed option label rather than creating a new value.

How does blur matching work?

Case-insensitive exact label match commits one unique option. Duplicate labels never commit on blur. Disabled options never commit on blur.

How are no-results announced?

A polite visually hidden status region announces when the list opens, when results become empty, and when results return — not on every keystroke.

Tokens used

component/radius/controlcombobox/popup-surfacecombobox/option-active-surfacesemantic/focus-ring

Known limitation

Beta supports local prefix/substring filtering only — no remote search, multi-select, clear button, or free-form custom values. Unmatched blur text reverts to the last committed option label.

Component API

Prop	Type	Default	Description
label	string	—	Visible field label via FormField.
options	ComboboxOption[]	—	Predefined value/label pairs.
value	string	—	Controlled selected option value.
inputValue	string	—	Controlled input text while editing.
open	boolean	—	Controlled popup open state.
filterMode	"prefix" \| "substring"	"prefix"	Local filtering strategy.
required	boolean	—	Requires a committed option value.

React example

Copy React example

"use client";

import { Combobox } from "@/components/ui/Combobox";

export function Example() {
  return (
    <Combobox
      label="Country"
      name="country"
      placeholder="Search countries"
      options={[
        { value: "us", label: "United States" },
        { value: "ca", label: "Canada" },
      ]}
    />
  );
}