Combobox

A text input that filters a long list of options as you type.

Short lists (under about 10): use Select.
Free text with suggestions: use an Autocomplete.

Install

Terminal

pnpm dlx shadcn@latest add @acme/combobox

Or import from the package: import { Combobox } from '@acme/react'

Examples

Basic

Billing country

Sets the tax rules for your invoices.

combobox-basic.tsx

'use client'

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from '@/components/ui/combobox'
import { Field, FieldDescription, FieldLabel } from '@/components/ui/field'

type Country = { value: string; label: string }

const countries: Country[] = [
  { value: 'au', label: 'Australia' },
  { value: 'br', label: 'Brazil' },
  { value: 'ca', label: 'Canada' },
  { value: 'de', label: 'Germany' },
  { value: 'in', label: 'India' },
  { value: 'jp', label: 'Japan' },
  { value: 'ke', label: 'Kenya' },
  { value: 'mx', label: 'Mexico' },
  { value: 'gb', label: 'United Kingdom' },
  { value: 'us', label: 'United States' },
]

export default function ComboboxBasic() {
  return (
    <Field className="max-w-xs">
      <FieldLabel>Billing country</FieldLabel>
      <Combobox items={countries}>
        <ComboboxInput placeholder="Start typing a country" />
        <ComboboxContent>
          <ComboboxEmpty>No matching countries.</ComboboxEmpty>
          <ComboboxList aria-label="Billing country">
            {(country: Country) => (
              <ComboboxItem key={country.value} value={country}>
                {country.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <FieldDescription>Sets the tax rules for your invoices.</FieldDescription>
    </Field>
  )
}

Props

Combobox props
Prop	Type	Default	Description
items (required)	T[]	—	The options. Objects with value and label filter by label.
value / defaultValue / onValueChange	T	—	Selected item.
multiple	boolean	—	Allow several selections.
ComboboxInput.showClear	boolean	true	Show a clear button.
ComboboxList.children (required)	(item: T) => ReactNode	—	Renders each row.
ComboboxList.aria-label	string	'Options'	Names the listbox; pass the field's label.

Keyboard
Key	Action
`Type`	Filters the list
`Arrow Down / Up`	Opens / moves highlight
`Enter`	Selects the highlighted option
`Escape`	Closes; again clears the input

Role: combobox + listbox
You provide: Label it with Field + FieldLabel.
A ComboboxEmpty message.
aria-label on ComboboxList matching the field label.
Built in: Result counts and the empty state are announced.
WCAG 2.2 criteria: 1.3.1, 2.1.1, 4.1.2, 4.1.3

Don’t

Require exact spelling: keep the filter forgiving.

Tokens