Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
combobox · base base · style base-lyraOpen under the product theme

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.

Theme
Density
Text
Status
Accent theme
Accent
combobox-filtering-a-list · base base · style base-lyraOpen under the product theme
combobox-filtering-a-list.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
combobox-no-match · base base · style base-lyraOpen under the product theme
combobox-no-match.tsx
"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 select instead.
  • Two to about five short options worth comparing at a glance.Use radio-group instead.

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.
KeyActionNotes
TabMoves focus into the control, onto the inputThe one tab stop. A second Tab reaches the trigger.
TypingFilters the list to the matchesContains match on the label. The popup opens as you type.
Arrow DownOpens the popup and moves the highlight into the listOpens a closed popup and highlights the first match.
Arrow Up, Arrow DownMoves the highlight between matchesThe popup holds the highlight while the input keeps the caret.
EnterChooses the highlighted match and closes the popupThe label fills the input and onValueChange reports the value.
EscapeCloses the popup without choosingThe input keeps its text.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.