Combo Box

Basic

A combo box combines a text input with a listbox, allowing users to filter options to match what they're looking for.

Installation

npx shadcn@latest add @intentui/combo-box

Composed components

Manual installation

npm i react-aria-components @intentui/icons

Anatomy

import {
  ComboBox,
  ComboBoxInput,
  ComboBoxContent,
  ComboBoxItem,
} from "@/components/ui/combo-box"

<ComboBox placeholder="Select a user" label="Users">
  <ComboBoxInput />
  <ComboBoxContent>
    <ComboBoxItem>John Lennon</ComboBoxItem>
    <ComboBoxItem>Paul McCartney</ComboBoxItem>
    <ComboBoxItem>George Harrison</ComboBoxItem>
    <ComboBoxItem>Ringo Starr</ComboBoxItem>
  </ComboBoxContent>
</ComboBox>

Using avatars

The combo box can be configured to display avatars instead of just regular text.

Section

A combo box can display items grouped together in sections.

Readonly

When the combo box is in a readonly state, it cannot be edited.

Label

If the children of a ComboBox.Item is a string, the ComboBox.Label will automatically wrap it. However, if you're including additional elements like an icon or avatar, you'll need to manually wrap the label, as shown below:

<ComboBox.Item id={item.id} textValue={item.name}>
  <Avatar src={item.image_url} />
  <ComboBox.Label>{item.name}</ComboBox.Label>
</ComboBox.Item>

Details description

If you need to provide more information about an option, use the ComboBox.Description component to display additional details.

Validation

If a user submits the form without selecting an item, an error message will appear.

Controlled

There are two ways to control the combo box: using the onInputChange prop or the onSelectionChange prop. These methods serve different purposes, as illustrated in the examples below. Both examples follow the same approach, defining id and textValue for the options.

When you only need the textValue of the selected option, use the onInputChange prop. However, if you need to obtain the actual id of the selected option, the onSelectionChange prop is the appropriate choice.

Input

This combo box is controlled by the onInputChange prop.

Selection

This combo box is controlled by the onSelectionChange prop.

Disabled

When the combo box is disabled, it becomes non-interactive and cannot be edited.