build69
Sign inGet API key
build69  /  Components  /  Selection & Choice  /  ComboboxAsync

ComboboxAsync

v1.0.9Updated 27 Aug 2026

Async-loading combobox with debounced fetch, optional creatable entries, multi-select with chips, free-solo input, and grouped results. Exports ComboboxAsync + ComboboxAsyncMulti.

View source← Back to catalog

Preview

Live · 10 stories
AsyncOpen ↗
▸Why this is recommendedcomboboxautocompleteasyncserver-search+4

ComboboxAsync loading its data asynchronously.

Recommended for+14
  • ✓Customer or supplier lookup against a server API
  • ✓Searching a product catalogue too large to preload
  • ✓Owner / assignee pickers backed by a user-search endpoint
  • ✓Address or place autocomplete
  • ✓Pick-or-create a customer while drafting an invoice
  • ✓Any picker over thousands of records that must be queried per keystroke
Tags+6
comboboxautocompleteasyncserver-searchcreatablefree-solotypeaheadremote
Features+4
  • Host-driven async loading via onSearchChange + options
  • Loading spinner and error panel with a Retry button
  • Creatable: "Create '<query>'" row when there is no exact match
  • Free-solo: commit arbitrary typed text as the value
  • Grouped results with headings plus a meta line per option
  • Enter commits the create / free-solo row
  • Custom trigger via the `trigger` prop
Not recommended for−2
  • ✕Static option sets already in memory (use Combobox)
  • ✕Selecting multiple values (use ComboboxAsyncMulti)
  • ✕Plain free-text entry with no suggestions (use Input)
  • ✕Command palettes and action menus (use Command)

Install

Ask your agent, or call the MCP tool directly. The resolved bundle is written into your project.

get_registry_item({ name: "ComboboxAsync" })

Usage

import { ComboboxAsync } from '@build69/ui';

<ComboboxAsync
  value={customerId}
  onValueChange={setCustomerId}
  options={results}
  onSearchChange={debouncedSearch}
  loading={isLoading}
  error={error}
  onRetry={refetch}
  creatable
  onCreate={(name) => createCustomer(name)}
  placeholder="Search or create a customer…"
/>

Tick variants in the left menu — each adds a tab with that variant’s real story source, the same code the preview above renders.

Props

PropTypeRequired
options

Current result set — the host replaces it in response to onSearchChange

ComboboxAsyncOption[]yes
onSearchChange

Fires on every keystroke; the host should debounce and fetch. Supplying it also turns off the built-in cmdk filter

(query: string) => void | Promise<void>—
value

Selected option value (or raw text when freeSolo)

string—
onValueChange

Fires on select; re-selecting the current value clears it

(value: string) => void—
loading

Show the loading spinner in the list

boolean—
error

Error message; replaces the list with an error panel

string—
onRetry

Shows a Retry button inside the error panel

() => void—
creatable

Show a "Create '<query>'" row when no option matches exactly

boolean—
onCreate

Called with the query on create; the host owns value assignment. Without it, the query is committed as the value

(query: string) => void—
freeSolo

Allow committing any typed text as the value

boolean—
placeholder

Trigger text when nothing is selected (default "Select…")

string—
trigger

Replace the default trigger button; the forwarded ref stays on the default trigger

React.ReactNode—
disabled

Disable the trigger

boolean—

Related

Platform docsAll componentsSource files