Combobox

A searchable dropdown component that combines an input with a list of options.

Installation


pnpm dlx bna-ui add combobox

Usage

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

<Combobox value={value} onValueChange={setValue}>
  <ComboboxTrigger>
    <ComboboxValue placeholder='Select framework...' />
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput placeholder='Search frameworks...' />
    <ComboboxList>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      <ComboboxItem value='react'>React</ComboboxItem>
      <ComboboxItem value='vue'>Vue</ComboboxItem>
      <ComboboxItem value='angular'>Angular</ComboboxItem>
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Examples

Default

With Groups

Multiple Selection

Disabled

With Custom Search

Form Integration

Large Dataset

API Reference

Combobox

The root component that manages the state and context for all child components.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The combobox components.
`value`	`string`	`""`	The selected value (single selection).
`onValueChange`	`(value: string) => void`	-	Callback when single value changes.
`values`	`string[]`	`[]`	The selected values (multiple selection).
`onValuesChange`	`(values: string[]) => void`	-	Callback when multiple values change.
`disabled`	`boolean`	`false`	Whether the combobox is disabled.
`multiple`	`boolean`	`false`	Whether multiple selection is enabled.

ComboboxTrigger

The button that triggers the combobox dropdown.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The trigger content (usually ComboboxValue).
`style`	`ViewStyle`	-	Additional styles for the trigger.
`error`	`boolean`	`false`	Whether to show error styling.

ComboboxValue

Displays the selected value or placeholder text.

Prop	Type	Default	Description
`placeholder`	`string`	`"Select..."`	Placeholder text when no value.
`style`	`TextStyle`	-	Additional styles for the text.

ComboboxContent

The modal container for the dropdown content.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The dropdown content.
`maxHeight`	`number`	`400`	Maximum height of the dropdown.

ComboboxInput

The search input field within the dropdown.

Prop	Type	Default	Description
`placeholder`	`string`	`"Search..."`	Placeholder text for the input.
`style`	`ViewStyle`	-	Additional styles for the container.
`autoFocus`	`boolean`	`true`	Whether to auto-focus the input.

ComboboxList

Container for the list of options with filtering capability.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The list items and groups.
`style`	`ViewStyle`	-	Additional styles for the list.

ComboboxEmpty

Displays when no items match the search query.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The empty state content.
`style`	`ViewStyle`	-	Additional styles for the container.

ComboboxGroup

Groups related options with an optional heading.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The group items.
`heading`	`string`	-	Optional heading for the group.

ComboboxItem

Individual selectable option within the combobox.

Prop	Type	Default	Description
`children`	`ReactNode`	-	The item content.
`value`	`string`	-	The value of the item.
`onSelect`	`(value: string) => void`	-	Callback when item is selected.
`disabled`	`boolean`	`false`	Whether the item is disabled.
`searchValue`	`string`	-	Custom value for search filtering.
`style`	`ViewStyle`	-	Additional styles for the item.

Accessibility

The Combobox component is built with accessibility in mind:

Full keyboard navigation support
Screen reader compatible with proper ARIA attributes
Focus management between trigger and dropdown
Escape key closes the dropdown
Search functionality works with assistive technologies
Proper color contrast for all states
Supports dynamic text sizing

Keyboard Shortcuts

Space/Enter: Open dropdown when trigger is focused
Escape: Close dropdown
Arrow Keys: Navigate through options
Enter: Select highlighted option
Tab: Move focus to next element
Type: Search for matching options

Color Picker Date Picker