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.

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. In single mode, selecting an item closes the dropdown. In multiple mode, items show checkboxes and the dropdown remains open.

When no value prop is provided, the text content of children is used as the value.

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 wrapped with Combobox.Group.

Prop

Type

Combobox.Separator Props

Visual divider between combobox items or groups.

Prop

Type

Examples

Basic

A simple combobox with search filtering built in. Type to filter options.

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>

With Icons

You can pass the leadingIcon prop to Combobox.Item to display icons before item text.

1<Combobox>
2  <Combobox.Input placeholder="Select a fruit" width={240} />
3  <Combobox.Content>
4    <Combobox.Item value="apple" leadingIcon={<Info size={16} />}>
5      Apple
6    </Combobox.Item>
7    <Combobox.Item value="banana" leadingIcon={<X size={16} />}>
8      Banana
9    </Combobox.Item>
10    <Combobox.Item value="grape" leadingIcon={<Home size={16} />}>
11      Grape
12    </Combobox.Item>
13    <Combobox.Item value="orange" leadingIcon={<Laugh size={16} />}>
14      Orange
15    </Combobox.Item>

With Label and Helper Text

The input supports label, helperText, and other InputField props.

1<Combobox>
2  <Combobox.Input
3    placeholder="Select a fruit"
4    label="Favorite Fruit"
5    helperText="Choose your favorite fruit"
6    width={240}
7  />
8  <Combobox.Content>
9    <Combobox.Item value="apple">Apple</Combobox.Item>
10    <Combobox.Item value="banana">Banana</Combobox.Item>
11    <Combobox.Item value="blueberry">Blueberry</Combobox.Item>
12    <Combobox.Item value="grapes">Grapes</Combobox.Item>
13  </Combobox.Content>
14</Combobox>

Groups and Separators

Organize items into groups with labels and visual separators. Groups and labels are automatically hidden when the user is searching.

1<Combobox>
2  <Combobox.Input placeholder="Search items" width={240} />
3  <Combobox.Content>
4    <Combobox.Group>
5      <Combobox.Label>Fruits</Combobox.Label>
6      <Combobox.Item value="apple">Apple</Combobox.Item>
7      <Combobox.Item value="banana">Banana</Combobox.Item>
8    </Combobox.Group>
9    <Combobox.Separator />
10    <Combobox.Group>
11      <Combobox.Label>Vegetables</Combobox.Label>
12      <Combobox.Item value="carrot">Carrot</Combobox.Item>
13      <Combobox.Item value="broccoli">Broccoli</Combobox.Item>
14    </Combobox.Group>
15  </Combobox.Content>

Multiple Selection

Pass the multiple prop to enable multi-select. Selected values appear as chips in the input. Items display checkboxes in multiple mode.

1<Combobox multiple>
2  <Combobox.Input placeholder="Select fruits" width={300} />
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>Mango</Combobox.Item>
9    <Combobox.Item>Pineapple</Combobox.Item>
10    <Combobox.Item>Strawberry</Combobox.Item>
11    <Combobox.Item>Watermelon</Combobox.Item>
12    <Combobox.Item>Kiwi</Combobox.Item>
13    <Combobox.Item>Lemon</Combobox.Item>
14    <Combobox.Item>Lime</Combobox.Item>
15    <Combobox.Item>Lemon</Combobox.Item>

Controlled

Use value and onValueChange for controlled behavior.

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>