Components
Combobox
A text input that narrows a list the product supplies as the reader types, then lets them choose one match.
Usage
pnpm dlx shadcn@latest add @opsinjs/combobox
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Combobox } from "@/components/ui/combobox"<Combobox
label="Medication"
placeholder="Search medications"
value={medication}
onValueChange={setMedication}
items={[
{ value: "amoxicillin", label: "Amoxicillin" },
{ value: "ibuprofen", label: "Ibuprofen" },
{ value: "paracetamol", label: "Paracetamol" },
]}
/>Examples
combobox · base base · style base-lyraOpen under the product themeFiltering 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.
combobox-filtering-a-list · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"
export default function ComboboxFilteringAList() {
const [city, setCity] = useState<string | null>("berlin")
return (
<div className="w-full max-w-xs">
<Combobox
label="City"
placeholder="Search cities"
value={city}
onValueChange={setCity}
items={[
{ value: "amsterdam", label: "Amsterdam" },
{ value: "berlin", label: "Berlin" },
{ value: "bogota", label: "Bogota" },
{ value: "cairo", label: "Cairo" },
{ value: "dakar", label: "Dakar" },
{ value: "helsinki", label: "Helsinki" },
{ value: "lisbon", label: "Lisbon" },
{ value: "manila", label: "Manila" },
{ value: "mumbai", label: "Mumbai" },
{ value: "nairobi", label: "Nairobi" },
{ value: "osaka", label: "Osaka" },
{ value: "quito", label: "Quito" },
{ value: "reykjavik", label: "Reykjavik" },
{ value: "santiago", label: "Santiago" },
{ value: "tokyo", label: "Tokyo" },
{ value: "warsaw", label: "Warsaw" },
]}
/>
</div>
)
}No match
Type something the list does not contain, such as "xyz". emptyMessage fills the
popup, announced politely.
combobox-no-match · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"
export default function ComboboxNoMatch() {
const [swatch, setSwatch] = useState<string | null>(null)
return (
<div className="w-full max-w-xs">
<Combobox
label="Swatch name"
placeholder="Search swatches"
emptyMessage="No swatch matches that. Check the spelling."
value={swatch}
onValueChange={setSwatch}
items={[
{ value: "amber", label: "Amber" },
{ value: "indigo", label: "Indigo" },
{ value: "sage", label: "Sage" },
{ value: "slate", label: "Slate" },
{ value: "teal", label: "Teal" },
]}
/>
</div>
)
}When to use it
Use it when
- One item from a list long enough that typing a few letters beats scrolling it: a city, a country, a product-owned medication name.
- A single choice where the reader knows roughly what they want and would rather type than hunt.
- A field that must stay compact, filtering a long list in place rather than pushing the form down.
Do not use it when
- A short fixed set that fits in a closed menu, so typing to filter buys nothing.Use
selectinstead. - Two to about five short options worth comparing at a glance.Use
radio-groupinstead.
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.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus into the control, onto the input | The one tab stop. A second Tab reaches the trigger. |
| Typing | Filters the list to the matches | Contains match on the label. The popup opens as you type. |
| Arrow Down | Opens the popup and moves the highlight into the list | Opens a closed popup and highlights the first match. |
| Arrow Up, Arrow Down | Moves the highlight between matches | The popup holds the highlight while the input keeps the caret. |
| Enter | Chooses the highlighted match and closes the popup | The label fills the input and onValueChange reports the value. |
| Escape | Closes the popup without choosing | The input keeps its text. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from ComboboxProps in registry/bases/base/combobox.tsx.
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.