Combobox

An autocomplete input with a filterable dropdown list. Supports controlled and uncontrolled modes.

Filterable List

Empty State

Installation

npx visor add combobox

This copies two files into your project:

components/ui/combobox/combobox.tsx — the component
components/ui/combobox/combobox.module.css — the styles

Usage

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxItem,
  ComboboxEmpty,
} from '@/components/ui/combobox/combobox';

<Combobox>
  <ComboboxInput placeholder="Pick a fruit..." />
  <ComboboxContent>
    <ComboboxItem value="apple">Apple</ComboboxItem>
    <ComboboxItem value="banana">Banana</ComboboxItem>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

API Reference

ComboboxProps

Prop	Type	Default	Description
`inputValue`	`string`	—	Controlled value of the search input.
`onInputChange`	`(value: string) => void`	—	Callback when the input value changes.
`value`	`string`	—	Controlled selected value.
`onSelect`	`(value: string) => void`	—	Callback when an item is selected.
`open`	`boolean`	—	Controlled open state of the dropdown.
`onOpenChange`	`(open: boolean) => void`	—	Callback when the open state changes.

Sub-components

Component	Element	Purpose
`Combobox`	`<div>`	Root provider managing open state, input value, and selection
`ComboboxInput`	`<input>`	Text input with `role="combobox"` for typing and filtering
`ComboboxContent`	`<div>` (portal)	Popover dropdown containing the listbox
`ComboboxItem`	`<li>`	Selectable option with `role="option"` and check indicator
`ComboboxEmpty`	`<li>`	Placeholder shown when no options match the filter
`ComboboxGroup`	`<li>`	Groups related options under an optional heading
`ComboboxSeparator`	`<li>`	Visual divider between groups or items

Accessibility

Input renders with role="combobox", aria-expanded, and aria-autocomplete="list"
The dropdown list renders with role="listbox"; each option has role="option"
aria-activedescendant tracks keyboard-focused option
Keyboard: Type to filter, Arrow Down/Up navigate options, Enter selects, Escape closes
Screen readers announce the number of available options when the list opens

Combobox

On this page