---
title: "Combobox"
description: "A text input that narrows a list the product supplies as the reader types, then lets them choose one match."
url: "https://opsinjs.pensievelabs.org/docs/components/combobox"
source: "https://opsinjs.pensievelabs.org/docs/components/combobox.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["autocomplete", "typeahead", "search select"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="combobox"
  status="shipped"
  questions="[
  &#x22;The filter is Base UI's default contains match, so an accented character, an abbreviation or a near-miss spelling may filter a real item away.&#x22;,
  &#x22;Nobody has listened to this in a screen reader, so whether the list narrowing and the empty line are announced is argued, not heard.&#x22;,
  &#x22;No contrast pair is measured and forced colours are unhandled, so the hairline, popup, highlight and tick are argued to survive rather than checked.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="combobox" unbuilt="false" importPath="@/components/ui/combobox" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

```tsx
import { Combobox } from "@/components/ui/combobox"
```

```tsx
<Combobox
  label="Medication"
  placeholder="Search medications"
  value={medication}
  onValueChange={setMedication}
  items={[
    { value: "amoxicillin", label: "Amoxicillin" },
    { value: "ibuprofen", label: "Ibuprofen" },
    { value: "paracetamol", label: "Paracetamol" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="combobox" />

### Filtering a list [#filtering-a-list]

`items` supplies a fictional set of cities and typing narrows it. `value` starts
on one city, so the input is filled and the tick is shown.

<ComponentPreview name="combobox-filtering-a-list" kind="example" align="start" />

### No match [#no-match]

Type something the list does not contain, such as "xyz". `emptyMessage` fills the
popup, announced politely.

<ComponentPreview name="combobox-no-match" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;One item from a list long enough that typing a few letters beats scrolling it: a city, a country, a product-owned medication name.&#x22;,
  &#x22;A single choice where the reader knows roughly what they want and would rather type than hunt.&#x22;,
  &#x22;A field that must stay compact, filtering a long list in place rather than pushing the form down.&#x22;,
]"
  avoid="[
  { case: &#x22;A short fixed set that fits in a closed menu, so typing to filter buys nothing.&#x22;, instead: &#x22;select&#x22; },
  { case: &#x22;Two to about five short options worth comparing at a glance.&#x22;, instead: &#x22;radio-group&#x22; },
]"
/>

## Accessibility [#accessibility]

Base UI renders `role="combobox"` on the input, which is the single tab stop,
`role="listbox"` on the popup and `role="option"` with `aria-selected` on each match.
The selection is a lucide Check and the highlight a neutral surface under
`data-highlighted`, so both survive greyscale. The input and the trigger floor a 44pt
target in rem and carry their own focus ring. The audit fixed two defects: the trigger
button now takes an `aria-label` built from the field's label, and the input's stray
`outline-none` no longer hides the keyboard focus ring. The list unfolds from the
input, and under `prefers-reduced-motion` only a short opacity crossfade remains.

**Residual items.**

* The label reaches a screen reader as `aria-label`, not a visible label element; a
  shared repair across the other input wrappers is still open.
* The live match count is not announced as the reader filters.
* No contrast pair is measured.

<KeyboardTable
  name="combobox"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the control, onto the input&#x22;,
    notes: &#x22;The one tab stop. A second Tab reaches the trigger.&#x22;,
  },
  {
    keys: &#x22;Typing&#x22;,
    action: &#x22;Filters the list to the matches&#x22;,
    notes: &#x22;Contains match on the label. The popup opens as you type.&#x22;,
  },
  {
    keys: &#x22;Arrow Down&#x22;,
    action: &#x22;Opens the popup and moves the highlight into the list&#x22;,
    notes: &#x22;Opens a closed popup and highlights the first match.&#x22;,
  },
  {
    keys: &#x22;Arrow Up, Arrow Down&#x22;,
    action: &#x22;Moves the highlight between matches&#x22;,
    notes: &#x22;The popup holds the highlight while the input keeps the caret.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Chooses the highlighted match and closes the popup&#x22;,
    notes: &#x22;The label fills the input and onValueChange reports the value.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Closes the popup without choosing&#x22;,
    notes: &#x22;The input keeps its text.&#x22;,
  },
]"
/>

<ContrastReport component="combobox" />

## Props interface [#props-interface]

<PropsTable name="ComboboxProps" />

`value` and `onValueChange` make this controlled, with no selection state of its
own. A `value` matching no item renders nothing chosen and raises a development
warning. `label` is required, and `items` comes from the product. Omitted,
`emptyMessage` falls back to a plain line.
