Loading…

Combobox

A searchable single-select built on the ARIA combobox pattern.

Forms
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add combobox

npm packages installed: radix-ui.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { Combobox } from "@/components/ui/combobox";

Examples

Every example the tests run, live and operable, side by side.

Default
Hidden Keywords
Rich Options
With Disabled Option
Controlled
Long List
Async Search
Clearable And Deselectable

API

Generated from the component's own types, so a prop cannot appear here without existing.

<Combobox>

Prop	Type	Default
`allowDeselect` Choosing the selected option again clears it, reporting `""`.	`boolean`	`false`
`defaultOpen`	`boolean`	`false`
`defaultValue`	`string`	—
`filter` Overrides how a search string is matched against an option.	`(search: string, haystack: string[]) => boolean`	`defaultComboboxFilter`
`loading` Results are on their way: the listbox is `aria-busy`, `ComboboxLoading` shows and `ComboboxEmpty` holds back, so "No results" never flashes first.	`boolean`	`false`
`onOpenChange`	`(open: boolean) => void`	—
`onSearchChange` Called as the search text changes, including the reset when it closes.	`(search: string) => void`	—
`onValueChange`	`(value: string) => void`	—
`open`	`boolean`	—
`searchDebounce` Milliseconds of quiet typing before `onSearchChange` fires.	`number`	`0`
`shouldFilter` Set `false` when the options are already the results for the search — for example when `onSearchChange` fetches them — so they are not filtered twice.	`boolean`	`true`
`value`	`string`	—
`children`	`ReactNode`	—

<ComboboxTrigger>

Prop	Type	Default
`placeholder` Shown when nothing is selected.	`string`	`"Select…"`

Plus every attribute of <button>.

<ComboboxContent>

Prop	Type	Default
`label` Names the popover, which carries role="dialog".	`string`	`"Search options"`

Every prop of Radix UI’s Popover.Content, plus className.

<ComboboxInput>

Prop	Type	Default
`clearable` Shows a button that clears the search while there is text to clear.	`boolean`	`false`

Plus every attribute of <input> except value, onChange.

<ComboboxList>

Plus every attribute of <div>.

<ComboboxItem>

Prop	Type	Default
`value` (required) The value reported by onValueChange, and the primary search term.	`string`	—
`disabled`	`boolean`	—
`keywords` Extra search terms that are not shown, such as synonyms or an id.	`string[]`	—
`children`	`ReactNode`	—

Plus every attribute of <div> except onSelect, children.

<ComboboxEmpty>

Plus every attribute of <div>.

<ComboboxLoading>

Plus every attribute of <div>.

Accessibility

The input owns role="combobox" with aria-expanded, aria-controls and aria-autocomplete; the list owns role="listbox" and each option role="option" with aria-selected. Focus stays in the input while arrow keys move aria-activedescendant, so typing is never interrupted. Arrow navigation wraps, Home/End jump, Enter selects the active option and Escape closes. With loading set, the listbox is aria-busy, ComboboxLoading is a status and the empty state waits for the answer. The optional clear button is a named button that returns focus to the input.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

allowDeselect

Choosing the selected option again clears it, reporting "".

boolean

false

defaultOpen

boolean

false

defaultValue

string

—

filter

Overrides how a search string is matched against an option.

(search: string, haystack: string[]) => boolean

defaultComboboxFilter

loading

Results are on their way: the listbox is aria-busy, ComboboxLoading shows and ComboboxEmpty holds back, so "No results" never flashes first.

boolean

false

onOpenChange

(open: boolean) => void

—

onSearchChange

Called as the search text changes, including the reset when it closes.

(search: string) => void

—

onValueChange

(value: string) => void

—

open

boolean

—

searchDebounce

Milliseconds of quiet typing before onSearchChange fires.

number

0

shouldFilter

Set false when the options are already the results for the search — for example when onSearchChange fetches them — so they are not filtered twice.

boolean

true

value

string

—

children

ReactNode

—

Prop

Type

Default

placeholder

Shown when nothing is selected.

string

"Select…"

Prop

Type

Default

label

Names the popover, which carries role="dialog".

string

"Search options"

Prop

Type

Default

clearable

Shows a button that clears the search while there is text to clear.

boolean

false

Prop

Type

Default

value

The value reported by onValueChange, and the primary search term.

string

—

disabled

boolean

—

keywords

Extra search terms that are not shown, such as synonyms or an id.

string[]

—

children

ReactNode

—