Combobox

Installation

$ npx shadcn@latest add https://goodui.dev/r/combobox.json

The file lands in components/goodui/combobox.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/combobox works too.

Usage

import * as React from "react"
import { Search } from "lucide-react"
import { Combobox, type ComboboxOption } from "@/components/goodui/combobox"

export function ClientField() {
  const [client, setClient] = React.useState<string | null>(null)
  return (
    <div className="flex flex-col gap-1.5">
      <label htmlFor="client" className="text-sm font-medium">Client</label>
      <Combobox
        id="client"
        className="w-full"
        icon={<Search />}
        placeholder="Search clients…"
        minChars={2}
        loadOptions={async (query, { signal }) => {
          const res = await fetch(`/api/clients?q=${encodeURIComponent(query)}`, { signal })
          const rows: { id: string; name: string; email: string }[] = await res.json()
          return rows.map((r) => ({ value: r.id, label: r.name, description: r.email, avatar: true }))
        }}
        creatable
        onCreate={async (name) => {
          const saved = await createClient(name)
          return { value: saved.id, label: saved.name }
        }}
        value={client}
        onValueChange={setClient}
        clearable
        name="clientId"
      />
    </div>
  )
}

When to use

Examples

<Combobox
  aria-label="Invitees"
  multiple
  creatable
  options={team.map((m) => ({ value: m.email, label: m.name, description: m.email, group: m.role, avatar: true }))}
  value={emails}
  onValueChange={setEmails}
  labels={{ create: (t) => `Invite “${t}” by email` }}
/>

<Combobox aria-label="Product" options={catalog} variant="filled" onValueChange={(value, option) => addLine(option)} />

<Combobox
  aria-label="Kunde"
  options={clients}
  placeholder="Kunden suchen…"
  labels={{
    clear: "Leeren",
    toggle: "Vorschläge anzeigen",
    create: (t) => `„${t}“ anlegen`,
    loading: "Suche…",
    empty: (q) => (q ? `Keine Treffer für „${q}“` : "Keine Einträge"),
    error: "Ergebnisse konnten nicht geladen werden.",
    retry: "Erneut versuchen",
    minChars: (n) => `Mindestens ${n} Zeichen eingeben`,
    results: (n) => `${n} Ergebnisse`,
  }}
/>

API reference

Accessibility

• •The input is role="combobox" with aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant (ARIA 1.2); focus stays in the input while the highlight moves.
• •The popup is role="listbox" (aria-multiselectable with multiple, aria-busy while loading) with role="option" rows carrying aria-selected, aria-disabled, aria-posinset and aria-setsize, so virtualized lists still announce the full count.
• •A polite live region announces the result count, “Searching…”, empty and error messages (all from labels).
• •Pass aria-label, or id with a visible <label htmlFor>. Chips are listed in visually hidden text referenced by aria-describedby; each chip's × is a button named by labels.remove.
• •The chevron button is out of the tab order (keyboard users have Arrow Down) and is named by labels.toggle. invalid sets aria-invalid.
• •Matched text is wrapped in <mark>, ignoring case and accents, and every word of the query is highlighted.

Motion

• •fade-scale (default): the list fades in from 0.97 scale and 4px on a spring (stiffness 520, damping 34, mass 0.7). slide: unrolls from the field with a clip and 10px move. stagger: rows slide in 4px, 25 ms apart (off for virtualized lists).
• •The list closes with a 120 ms fade. Chips pop in and out (scale from 0.8) and the others shift into place; the underline variant draws its bar in 250 ms.
• •Reduced motion: the list only fades, rows do not stagger, chips appear without layout animation, CSS transitions are off and the loading spinner slows down.

• •Local matching uses a pre-folded index built once per options change; each keystroke is one pass that checks every word and ranks label prefix, word start, then anywhere.
• •Above virtualThreshold (100 rows by default) only the rows in view plus a 200px margin are rendered; rows get a fixed height (taller when options have descriptions), so End, PageDown and scrolling stay smooth on 10k+ rows.
• •Async search is debounced (250 ms), aborts the previous request through AbortSignal and caches results per query (cache={false} to turn off).

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

FAQ

Related