Combobox

Filterable single-select with an animated custom listbox, built on the dropdown open/close machine

Category: inputs · WCAG 2.2-AA · select, combobox, dropdown, filter, search

Sizes

States

closed
open
error

Props

Prop	Type	Default	Description
`id`	`string`	—	Base id for the input and its listbox/aria wiring; auto-generated when omitted.
`options`	`ComboboxOption[]`	—	The selectable options.
`value`	`string`	—	The controlled value.
`defaultValue`	`string`	—	The initial value when uncontrolled.
`onValueChange`	`(value: string \| undefined) => void`	—	Called with the selected option value (or undefined when cleared).
`onChange`	`(value: string \| undefined) => void`	—	Deprecated: use onValueChange (same string \| undefined).
`clearable`	`boolean`	`false`	When true, shows a control to clear the selected value.
`searchable`	`boolean`	`true`	When true, shows a search/filter input.
`label`	`string`	—	Text label for the control.
`hint`	`string`	—	Supplementary hint text shown with the control.
`error`	`string`	—	Error message shown when the value is invalid.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Visual size of the component (e.g. 'sm', 'md', 'lg').
`disabled`	`boolean`	`false`	When true, disables the control and removes it from the tab order.
`labels`	`ComboboxLabels`	—	Overrides for the component’s user-visible strings (i18n).
`className`	`string`	—	Additional CSS class names merged onto the root element.

Design tokens

--cascivo-color-surface
--cascivo-color-surface-overlay
--cascivo-color-bg-subtle
--cascivo-color-border
--cascivo-color-border-strong
--cascivo-color-text
--cascivo-color-text-muted
--cascivo-color-text-subtle
--cascivo-color-accent
--cascivo-color-danger
--cascivo-radius-input
--cascivo-radius-md
--cascivo-radius-sm
--cascivo-shadow-lg
--cascivo-motion-enter
--cascivo-z-dropdown

When to use

Single-select from a long list where type-to-filter makes finding an option faster
Form fields where the value is one of many known options (country, assignee, repository)

When not to use

Short option lists (≈2–7) where filtering adds no value — use Select or SegmentedControl
Selecting multiple values — use MultiSelect
Triggering actions or commands — use Dropdown or CommandMenu

How to build an accessible Combobox in React →

Examples

Basic combobox

<Combobox
  label="Country"
  options={[
    { value: 'us', label: 'United States' },
    { value: 'de', label: 'Germany' },
    { value: 'fr', label: 'France' },
  ]}
  onChange={(value) => console.log(value)}
/>

Related components

Select — Use for short lists that do not need type-to-filter
MultiSelect — Use when more than one value can be selected
CommandMenu — Use the Cmd+K palette for command/navigation search rather than value selection

← Back to docs