Combobox

Overview

<Combobox /> is the canonical searchable-select primitive — a <Select /> with a typeable input that filters its option list as the user types. <MultiCombobox /> is the same component with multi-select semantics: selected values render as removable <Badge> chips before the input, Backspace on an empty query removes the last chip.

Combobox sits at the intersection of three component families:

• Form-control — same controlBase + variantColorMatrix shell as <Input /> / <Textarea /> / <Select />. Combobox is the fourth consumer of the shared matrix.
• Overlay — reuses Select's listbox surface, item recipe, motion, and usePosition (matchTriggerWidth middleware), so the dropdown reads as a sibling of Select / Menu / Popover.
• List keyboard — reuses _shared/useListKeyboard.ts, validated for a third time (Menu → Select → Combobox). The hook's filter-driven getItems() accessor was designed precisely for this case where the visible item set changes on every keystroke.

When to use

• A picker bound to a long list (countries, tags, users) where typing-to-narrow saves clicks.
• A multi-select tag input — pass creatable + onCreateOption for the canonical tag UX.
• An autocomplete bound to a remote API — pass loadOptions with debouncing handled by the built-in useDeferredFilter.

When NOT to use

• A short fixed list (< 8 options) with no search benefit → use <Select />.
• A free-form text input with hints (no commitment to a value) → use <Input /> with a separate suggestion popover.
• A command launcher (actions, not values) → use the future <CommandPalette />.

Anatomy

<Combobox|MultiCombobox
  options=[…]                  // static
  loadOptions={async (q) => …} // OR async — overrides static when both passed
  value=…                      // string | null   (single)
                               // string[]        (multi)
  onChange=…
  inputValue=…
  onInputValueChange=…
  placeholder=…
  variant size color           // same vocab as Input / Select
  matchStrategy="substring|startsWith|fuzzy|custom"
  filterOption=(opt, query) => boolean   // wins over matchStrategy
  creatable + onCreateOption
  clearable closeOnSelect openOnFocus
  debounceMs loadingState
  open defaultOpen onOpenChange placement matchTriggerWidth
  renderOption renderEmpty renderLoading renderError renderCreateOption
  disabled invalid required name
  portalContainer translations
  id aria-label aria-labelledby aria-describedby
  className style sx
  inputProps                    // pass-through to the underlying <input>
/>

<Combobox|MultiCombobox
  options=[…]                  // static
  loadOptions={async (q) => …} // OR async — overrides static when both passed
  value=…                      // string | null   (single)
                               // string[]        (multi)
  onChange=…
  inputValue=…
  onInputValueChange=…
  placeholder=…
  variant size color           // same vocab as Input / Select
  matchStrategy="substring|startsWith|fuzzy|custom"
  filterOption=(opt, query) => boolean   // wins over matchStrategy
  creatable + onCreateOption
  clearable closeOnSelect openOnFocus
  debounceMs loadingState
  open defaultOpen onOpenChange placement matchTriggerWidth
  renderOption renderEmpty renderLoading renderError renderCreateOption
  disabled invalid required name
  portalContainer translations
  id aria-label aria-labelledby aria-describedby
  className style sx
  inputProps                    // pass-through to the underlying <input>
/>

• Single root element — Combobox is not a compound component; it uses a props-driven API (options, renderOption, filterOption, renderEmpty, …).
• Two exports for type safety — <Combobox> pins value: string | null; <MultiCombobox> pins value: string[]. Both render the same internal implementation; the only behavior delta is "close on select?" and "render tag chips?".

Variants

The input shell reuses Input / Textarea / Select's 4 × 7 form-control matrix verbatim — adding a color or variant happens once in _shared/variantColorMatrix.ts and all four surfaces light up.

Sizes

min-h (not h) because multi-mode tags wrap onto multiple lines; the shell grows with content to keep every chip visible.

Filter strategies

Want ranked fuzzy (Fuse.js / fzf-style)? Bring your own ranker via filterOption — the bundled fuzzy is intentionally yes-or-no with no scoring, because shipping a scorer would force a ranking opinion that's almost always wrong for some consumer.

Async loading

<Combobox
  loadOptions={async (query, { signal }) => {
    const res = await fetch(`/api/users?q=${encodeURIComponent(query)}`, { signal });
    if (!res.ok) throw new Error('Failed to load users');
    return (await res.json()).map((u: User) => ({ value: u.id, label: u.name }));
  }}
  debounceMs={300}
/>

<Combobox
  loadOptions={async (query, { signal }) => {
    const res = await fetch(`/api/users?q=${encodeURIComponent(query)}`, { signal });
    if (!res.ok) throw new Error('Failed to load users');
    return (await res.json()).map((u: User) => ({ value: u.id, label: u.name }));
  }}
  debounceMs={300}
/>

The bundled useDeferredFilter hook:

1. Debounces query changes by debounceMs (default 300).
2. Aborts the previous fetch via AbortController so stale results never overwrite fresh ones.
3. Switches loadingState between 'idle' | 'loading' | 'ready' | 'empty' | 'error'.
4. Cancels the in-flight controller on unmount so the promise resolves harmlessly.

The hook is exported publicly (useDeferredFilter) so future async-list components (CommandPalette, search dropdowns) can reuse the exact lifecycle.

Creatable mode

<MultiCombobox
  options={existingTags}
  value={selectedTags}
  onChange={setSelectedTags}
  creatable
  onCreateOption={(label) => ({ value: slugify(label), label })}
/>

<MultiCombobox
  options={existingTags}
  value={selectedTags}
  onChange={setSelectedTags}
  creatable
  onCreateOption={(label) => ({ value: slugify(label), label })}
/>

When creatable is on and the current query doesn't exactly match an existing option, a + Create "{query}" row appears at the tail of the list. Activating it (Enter / click) calls onCreateOption(query) and adds the resulting option to the selection. Supports both sync and Promise<Option> returns.

Form integration

Pass name and the component emits hidden <input type="hidden"> siblings — one for single mode, one per selected value for multi mode (so form serialization yields name=a&name=b&name=c exactly as a native <select multiple> would).

<form>
  <Combobox name="country" required placeholder="Pick a country" options={…} />
  <MultiCombobox name="skills" placeholder="Pick skills" options={…} />
</form>

<form>
  <Combobox name="country" required placeholder="Pick a country" options={…} />
  <MultiCombobox name="skills" placeholder="Pick skills" options={…} />
</form>

Accessibility

W3C ARIA Combobox + Listbox pattern (APG 1.2):

• Input — role="combobox" + aria-haspopup="listbox" + aria-expanded + aria-controls (only when open) + aria-autocomplete="list" + aria-activedescendant pointing to the currently-highlighted option id. aria-multiselectable is set on the listbox in multi mode.
• Listbox — role="listbox" + aria-labelledby the trigger.
• Options — role="option" + aria-selected + aria-disabled for disabled items + data-highlighted="true" for the keyboard-highlighted row.
• Tags (multi) — rendered via <Badge removable>; each remove button gets aria-label={t.removeTag(label)}.
• useFormFieldA11y bridges id / aria-invalid / aria-required / aria-describedby from the root onto the input — same hook Input / Textarea / Select use.

Keyboard

Type-ahead from useListKeyboard is intentionally disabled on Combobox — the input itself is the search affordance, so intercepting printable keys would prevent the query from updating. Filtering is the type-ahead, only better.

axe-core: 0 violations across single + multi, all four variants, and the disabled / invalid / required states.

Examples

Theming

defineTheme({
  components: {
    Combobox: {
      defaultProps: { matchStrategy: 'fuzzy', clearable: false },
      styleOverrides: {
        wrapper: 'shadow-sm',
        input: '',
        content: 'shadow-xl',
        item: 'rounded-md',
        groupLabel: 'text-fg',
        empty: '',
        loading: '',
        error: '',
        createRow: 'text-primary',
        clearButton: '',
      },
    },
  },
});

defineTheme({
  components: {
    Combobox: {
      defaultProps: { matchStrategy: 'fuzzy', clearable: false },
      styleOverrides: {
        wrapper: 'shadow-sm',
        input: '',
        content: 'shadow-xl',
        item: 'rounded-md',
        groupLabel: 'text-fg',
        empty: '',
        loading: '',
        error: '',
        createRow: 'text-primary',
        clearButton: '',
      },
    },
  },
});

Per-instance overrides via <Combobox className sx style /> merge on top of theme overrides, which merge on top of the recipe — same precedence chain Input / Select use.

Headless layer

Three pure helpers + one hook are exported alongside the components:

These are deliberately framework-light (no DOM, no React-only dependencies beyond useDeferredFilter) so they can be reused outside Combobox.