Combo Box

Installation

Install the component via the CLI in one command.

npx shadcn@latest add @intentui/combo-box

Composed components

Manual installation

Use this approach if you prefer to install and wire up the component yourself instead of using the CLI.

npm install react-aria-components @heroicons/react

Anatomy

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

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

Examples

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 ComboBoxItem is a string, the ComboBoxLabel 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:

<ComboBoxItem id={item.id} textValue={item.name}>
  <Avatar src={item.image_url} />
  <ComboBoxLabel>{item.name}</ComboBoxLabel>
</ComboBoxItem>

Details description

If you need to provide more information about an option, use the ComboBoxDescription 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.

Multiple select

Set selectionMode="multiple" to allow multi-select, and use TagGroup to display the selected items.

Custom value

By default, the combo box only allows selecting from the provided options. However, you can enable users to enter custom values by setting allowsCustomValue to true. This allows users to input values that are not part of the predefined options.

Disabled

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

Component API

ComboBox

The ComboBox component combines an input with selectable options.

ComboBoxContent

The ComboBoxContent component renders the combo box option list.

ComboBoxInput

The ComboBoxInput component renders the searchable combo box input.

ComboBoxValue

The ComboBoxValue component renders the selected combo box value.

ComboBoxItem

The ComboBoxItem component represents one combo box option.

ComboBoxLabel

The ComboBoxLabel component renders the primary text for an option.

ComboBoxDescription

The ComboBoxDescription component renders supporting text for an option.

ComboBoxSection

The ComboBoxSection component groups related combo box options.

See the React Aria for the full API reference.