build69
build69  /  Components  /  Selection & Choice  /  Combobox

Combobox

v1.0.23Updated 20 Oct 2026

Searchable single- or multi-select that composes Popover + Command. Hand-rolled — single via Combobox, multi via MultiCombobox.

View source← Back to catalog

Preview

Live · 11 stories
DefaultOpen ↗
▸Why this is recommendedcomboboxselectsearchautocomplete+4

The default, out-of-the-box Combobox.

Recommended for+14
  • ✓Choice fields with more than 10 options
  • ✓Country / language pickers with search
  • ✓Owner or assignee selectors on a task form
  • ✓Picking a framework, category, or status from a long list
  • ✓Any select where the user needs to type to narrow the list
Tags+6
comboboxselectsearchautocompletedropdowntypeaheadsingle-selectdefault
Features+4
  • Searchable single-select with a filter input
  • Opt-in multiple mode (checkbox rows + chips)
  • Flat or grouped options with headings and separators
  • Custom trigger via the `trigger` prop
  • Server-side filtering hook via `onSearchChange`
  • Disabled options and disabled field
  • Composes Popover + Command
  • Labelled by FormField: id and aria-* land on the role=combobox trigger, which then fills the field column
Not recommended for−2
  • ✕Small choice sets (use Select or RadioGroup)
  • ✕Free-text entry (use Input)
  • ✕Options fetched per keystroke with loading and error states (use ComboboxAsync)
  • ✕Dedicated multi-select with an overflow count (use MultiCombobox)

Install

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

get_registry_item({ name: "Combobox" })

Usage

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

<Combobox
  options={[{ value: 'th', label: 'Thailand' }, { value: 'sg', label: 'Singapore' }]}
  value={country}
  onValueChange={setCountry}
  placeholder="Select country"
/>

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

Flat or grouped options; grouped entries render headings with separators

ComboboxOption[] | ComboboxGroup[]yes
value

Selected value — string in single mode, string[] when `multiple`

string | string[]—
onValueChange

Fires on select/deselect; signature follows `multiple`

(value: string) => void | (value: string[]) => void—
multiple

Multi-select mode: checkbox rows, chips in the trigger, popover stays open

boolean—
placeholder

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

string—
searchPlaceholder

Placeholder for the filter input (default "Search…")

string—
emptyMessage

Shown when no option matches (default "No results.")

string—
onSearchChange

Called as the user types — use it to fetch/filter options server-side. Also called with an empty string when the popover closes, because the search field is discarded with it, so a host that mirrors the query never keeps a stale one

(search: string) => void—
onOpenChange

Fires on every open and close of the popover, including the programmatic close after a selection

(open: boolean) => void—
trigger

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

React.ReactNode—
disabled

Disable the trigger

boolean—
contentClassName

Class applied to the popover content

string—
scrollbar

How the option list draws its scrollbar once it overflows — forwarded to CommandList. Default 'thin': a visible themed bar, because the height cap is the only thing hiding the remaining options

'thin' | 'hidden' | 'auto'—
listMaxHeight

Cap the option list's height (number = px, string = any CSS length such as '50vh'). Omitted, the list keeps CommandList's 18rem default

number | string—
id

DOM id set on the trigger — a <label htmlFor> (or FormField) names the control through it

string—
aria-label

Accessible name for the trigger when there is no visible label

string—
aria-labelledby

Id(s) of the visible label element(s) that name the trigger

string—
aria-describedby

Id(s) of hint or error text that describe the trigger

string—
aria-invalid

Mark the trigger invalid — FormField clones this in from its error prop

boolean—
aria-required

Mark the trigger required — FormField clones this in from its required prop

boolean—
invalid

Mark the field invalid (destructive ring); aria-invalid wins when both are set

boolean—
required

Mark the field required (aria-required on the trigger)

boolean—
className

Class applied to the trigger; a width here wins over the default (w-full inside a FormField, the standalone width otherwise)

string—

Related

Platform docsAll componentsSource files