Combobox

An input field with an attached dropdown that allows users to search and select from a list of options.

Usage

1import { Combobox } from "@raystack/apsara";

Combobox Props

The Combobox component is composed of several parts, each with their own props.

The root element is the parent component that manages the combobox state including open/close, input value, and selection. It is built using Ariakit ComboboxProvider and Radix Popover.

Prop

Type

Combobox.Input Props

The input field that triggers the combobox dropdown and allows users to type and filter options.

Prop

Type

Combobox.Content Props

The dropdown container that holds the combobox items.

Prop

Type

Combobox.Item Props

Individual selectable options within the combobox.

Prop

Type

Combobox.Group Props

A way to group related combobox items together.

Prop

Type

Combobox.Label Props

Renders a label in a combobox group. This component should be used inside Combobox.Group.

Prop

Type

Combobox.Separator Props

Visual divider between combobox items or groups.

Prop

Type

Examples

Basic Combobox

A simple combobox with search functionality.

1<Combobox>
2  <Combobox.Input placeholder="Enter a fruit" />
3  <Combobox.Content>
4    <Combobox.Item>Apple</Combobox.Item>
5    <Combobox.Item>Banana</Combobox.Item>
6    <Combobox.Item>Grape</Combobox.Item>
7    <Combobox.Item>Orange</Combobox.Item>
8  </Combobox.Content>
9</Combobox>

Size

The combobox input supports different sizes.

1<Flex align="center" gap="large">
2  <Combobox>
3    <Combobox.Input size="small" placeholder="Small combobox" />
4    <Combobox.Content>
5      <Combobox.Item>Option 1</Combobox.Item>
6      <Combobox.Item>Option 2</Combobox.Item>
7    </Combobox.Content>
8  </Combobox>
9  <Combobox>
10    <Combobox.Input placeholder="Large combobox" />
11    <Combobox.Content>
12      <Combobox.Item>Option 1</Combobox.Item>
13      <Combobox.Item>Option 2</Combobox.Item>
14    </Combobox.Content>
15  </Combobox>
16</Flex>

Multiple Selection

To enable multiple selection, pass the multiple prop to the Combobox root element.

When multiple selection is enabled, the value, onValueChange, and defaultValue will be an array of strings. Selected items are displayed as chips in the input field.

1<Combobox multiple>
2  <Combobox.Input placeholder="Select fruits..." />
3  <Combobox.Content>
4    <Combobox.Item>Apple</Combobox.Item>
5    <Combobox.Item>Banana</Combobox.Item>
6    <Combobox.Item>Grape</Combobox.Item>
7    <Combobox.Item>Orange</Combobox.Item>
8    <Combobox.Item>Pineapple</Combobox.Item>
9    <Combobox.Item>Mango</Combobox.Item>
10  </Combobox.Content>
11</Combobox>

Groups and Separators

Use Combobox.Group, Combobox.Label, and Combobox.Separator to organize items into logical groups.

1<Combobox>
2  <Combobox.Input placeholder="Enter a fruit" />
3  <Combobox.Content>
4    <Combobox.Group>
5      <Combobox.Label>Fruits</Combobox.Label>
6      <Combobox.Item>Apple</Combobox.Item>
7      <Combobox.Item>Banana</Combobox.Item>
8    </Combobox.Group>
9    <Combobox.Separator />
10    <Combobox.Group>
11      <Combobox.Label>Vegetables</Combobox.Label>
12      <Combobox.Item>Carrot</Combobox.Item>
13      <Combobox.Item>Broccoli</Combobox.Item>
14    </Combobox.Group>
15  </Combobox.Content>
16</Combobox>

Controlled

You can control the combobox value and input value using the value, onValueChange, inputValue, and onInputValueChange props.

1(function ControlledDemo() {
2  const [value, setValue] = React.useState("");
3  const [inputValue, setInputValue] = React.useState("");
4

5  return (
6    <Flex direction="column" gap="medium">
7      <Text>Selected: {value || "None"}</Text>
8      <Combobox
9        value={value}
10        onValueChange={setValue}
11        inputValue={inputValue}
12        onInputValueChange={setInputValue}
13      >
14        <Combobox.Input placeholder="Enter a fruit" />
15        <Combobox.Content>
16          <Combobox.Item>Apple</Combobox.Item>
17          <Combobox.Item>Banana</Combobox.Item>
18          <Combobox.Item>Grape</Combobox.Item>
19        </Combobox.Content>
20      </Combobox>
21    </Flex>
22  );
23})

Accessibility

The Combobox component follows WAI-ARIA guidelines:

  • Input has role combobox
  • Content has role listbox
  • Items have role option
  • Supports keyboard navigation (Arrow keys, Enter, Escape)
  • ARIA labels and descriptions for screen readers
  • Focus management between input and listbox