Skip to content
Hazine

Async Search Combobox

Combobox that asks a remote source as the user types, with debounced requests and a popup that shows skeleton rows, results, an empty state or an error with Retry. Use when the option set is too large to ship.

How it differs. Every remote state lives inside the popup: minimum characters hint, skeleton rows, capped result count, empty and error panels with one action each, and stale responses dropped.

Install

pnpm dlx shadcn@latest add @hazine/combobox-async-search

Adds 1 file, 4 shadcn primitives (button, command, popover, skeleton), 1 Hazine item (@hazine/use-controllable-state), and 1 package (lucide-react).

First time? Add the registry to components.json
{
  "registries": {
    "@hazine": "https://api.hazine.dev/r/{name}.json"
  }
}

Needed once per project. Items resolve each other through the @hazine namespace.

Props16

loadOptionsrequired
(query: string, signal: AbortSignal) => Promise<ComboboxAsyncSearchResult>
Runs the search. Reject to show the error row. Abort on `signal` to cancel a stale request.
value
ComboboxAsyncSearchOption | null
The chosen option. The whole option is kept, since its label cannot be looked up without a request.
defaultValue
ComboboxAsyncSearchOption | null = null
onValueChange
(value: ComboboxAsyncSearchOption | null) => void
open
boolean
defaultOpen
boolean = false
onOpenChange
(open: boolean) => void
query
string
defaultQuery
string = ""
onQueryChange
(query: string) => void
minQueryLength
number = 2
Characters needed before a request is sent.
debounceMs
number = 250
Quiet time after the last keystroke before a request is sent.
placeholder
string = "Select an option"
Trigger text while nothing is chosen.
searchPlaceholder
string = "Search"
Placeholder and accessible name of the search field.
labels
Partial<ComboboxAsyncSearchLabels>
name
string
Adds a hidden input so the chosen value is submitted with a form.

Also accepts every prop of Omit< React.ComponentProps<typeof Button>, "value" | "defaultValue" | "name" | "children" | "asChild" | "type" >.

Accessibility

Keyboard
Keyboard support for Async Search Combobox
KeyEffect
Enter, Space or Arrow Down on the triggerOpens the popup and moves focus to the search field
Arrow Up, Arrow DownMoves the active option
Home, EndMoves to the first or last option
EnterChooses the active option and closes the popup, or sends the request again after an error
TabMoves from the search field to Clear search or Retry when one is shown
Enter or Space on Clear search or RetryRuns the action and returns focus to the search field
EscapeCloses the popup and returns focus to the trigger
Screen reader

A button opens a labelled popup. The search field inside is the combobox and controls a listbox through aria-activedescendant. The minimum characters hint describes the search field. The list is aria-busy while loading, counts go to a polite status region and a failed request to an alert.

  • Announces: Searching
  • Announces: Showing {shown} of {total} results. Keep typing to narrow.
  • Announces: {total} results
  • Announces: No results for "{query}".
  • Announces: Results could not be loaded. Check your connection, then retry.
Reduced motion
Skeleton rows stop pulsing. The popup keeps the host popover transition.
Checked
Not checked yet. Automated results appear here once CI has run.

Dependencies6

  • button
  • command
  • popover
  • skeleton
  • @hazine/use-controllable-state
  • lucide-react

Filled chips are registry items the CLI adds for you. Outlined chips are npm packages.

Tokens shipped0

None. The item is styled by the tokens your theme already has.

More in Selection Controls