Combobox

Searchable select: a button trigger opening a filterable option list in a popover. Works controlled (value + onValueChange) or uncontrolled; supports virtualization for large lists.

Usage

@desk/ui/components/combobox

<Field className="w-72">
  <FieldLabel htmlFor="finish-filter">Filter by finish</FieldLabel>
  <FieldContent>
    <Combobox items={FINISHES} placeholder="Any finish…" />
  </FieldContent>
</Field>

Best practices

Use Combobox when the user filters/searches a long list; use Select for a short closed list, or a domain variant like CountryCombobox for known sets.
onValueChange fires with "" when the current selection is toggled off — treat empty string as "cleared", not as a real value.
For lists in the hundreds+, pass virtualization={{ enabled: true }} so only visible rows mount instead of every CommandItem.
Provide items as { label, value }[] — the visible text comes from label while selection is tracked by value.

Props

Prop	Type	Default	Description
buttonClassName	`string`		Button class name
contentClassName	`string`		Class name for the popover content panel
data-testid	`string`		Test id for the trigger button
disabled	`boolean`		Whether disabled
items(required)	`ComboboxItem[]`		List of items
onValueChange	`(value: string) => void`		Called with the selected value, or `""` when the selection is toggled off.
placeholder	`string`	`"Select…"`	Placeholder text
size	`ResponsiveSize`	`"xl"`	Trigger size — a single token or a per-breakpoint object like `{ base: "sm", md: "xl" }`. Forwarded to the underlying Button.
value	`string`		Selected value; provide (with `onValueChange`) for controlled use, omit for uncontrolled.
virtualization	`ComboboxVirtualizationOptions`		Virtualization settings for large item sets.

Also exports

interfaceComboboxItem
interfaceComboboxProps
interfaceComboboxVirtualizationOptions

Composition

Builds on

Button, Command, Icon, Popover

Used by

CountryCombobox