Select

Displays a list of options for the user to pick from—triggered by a button.

Anatomy

Import and assemble the component:

1import { Select } from "@raystack/apsara";
2

3<Select>
4  <Select.Trigger />
5  <Select.Content>
6    <Select.Group>
7      <Select.Label />
8      <Select.Item />
9    </Select.Group>
10    <Select.Separator />
11  </Select.Content>
12</Select>

API Reference

Root

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

The root element is the parent component that holds the select. Using the autocomplete prop, you can enable autocomplete functionality. Autcomplet is built using Ariakit ComboboxProvider

Prop

Type

Trigger

The button that triggers the Select.

Prop

Type

Content

The container that holds the Select items.

Prop

Type

Item

Individual clickable options within the Select.

Prop

Type

Group

A way to group related Select items together.

Prop

Type

Label

Renders a label in a Select group. This component can only be used inside Select.Group

Prop

Type

Separator

Visual divider between Select items or groups.

Prop

Type

Examples

Basic Select

1<Select>
2  <Select.Trigger aria-label="Fruit selection">
3    <Select.Value placeholder="Select a fruit" />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Item value="apple">Apple</Select.Item>
7    <Select.Item value="banana">Banana</Select.Item>
8  </Select.Content>
9</Select>

Icon

You can pass leadingIcon prop to Select.Item to include items

1<Select>
2  <Select.Trigger aria-label="Fruit selection">
3    <Select.Value placeholder="Select a fruit" />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Item value="apple" leadingIcon={<Info size={16} />}>
7      Apple
8    </Select.Item>
9    <Select.Item value="banana" leadingIcon={<X size={16} />}>
10      Banana
11    </Select.Item>
12    <Select.Item value="grape" leadingIcon={<Home size={16} />}>
13      Grape
14    </Select.Item>
15    <Select.Item value="Orange" leadingIcon={<Laugh size={16} />}>

Size

1<Flex align="center" gap="large">
2  <Select>
3    <Select.Trigger size="small">
4      <Select.Value placeholder="Small select" />
5    </Select.Trigger>
6    <Select.Content>
7      <Select.Item value="1">Option 1</Select.Item>
8      <Select.Item value="2">Option 2</Select.Item>
9    </Select.Content>
10  </Select>
11  <Select>
12    <Select.Trigger>
13      <Select.Value placeholder="Small select" />
14    </Select.Trigger>
15    <Select.Content>

Variant

1<Select>
2  <Select.Trigger>
3    <Select.Value placeholder="Select..." />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Item value="all">All</Select.Item>
7    <Select.Item value="active">Active</Select.Item>
8    <Select.Item value="inactive">Inactive</Select.Item>
9  </Select.Content>
10</Select>

With Separator

1<Select>
2  <Select.Trigger>
3    <Select.Value placeholder="Select..." />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Group>
7      <Select.Item value="1">Option 1</Select.Item>
8      <Select.Item value="2">Option 2</Select.Item>
9    </Select.Group>
10    <Select.Separator />
11    <Select.Group>
12      <Select.Item value="3">Option 3</Select.Item>
13      <Select.Item value="4">Option 4</Select.Item>
14    </Select.Group>
15  </Select.Content>

Multiple Selection

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

When multiple selection is enabled, the value, onValueChange, and defaultValue will be an array of strings.

1<Select multiple>
2  <Select.Trigger>
3    <Select.Value placeholder="Select..." />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Item value="1">Option 1</Select.Item>
7    <Select.Item value="2">Option 2</Select.Item>
8    <Select.Item value="3">Option 3</Select.Item>
9    <Select.Item value="4">Option 4</Select.Item>
10    <Select.Item value="5">Option 5</Select.Item>
11    <Select.Item value="6">Option 6</Select.Item>
12    <Select.Item value="7">Option 7</Select.Item>
13    <Select.Item value="8">Option 8</Select.Item>
14    <Select.Item value="9">Option 9</Select.Item>
15    <Select.Item value="10">Option 10</Select.Item>

Autocomplete

To enable autocomplete, pass the autocomplete prop to the Select root element.

By default, only select items are filtered using a simple match. For more advanced control, set autocompleteMode="manual" and implement your own custom filtering logic.

1<Select autocomplete>
2  <Select.Trigger>
3    <Select.Value placeholder="Select..." />
4  </Select.Trigger>
5  <Select.Content>
6    <Select.Group>
7      <Select.Item value="1">Option 1</Select.Item>
8      <Select.Item value="2">Option 2</Select.Item>
9    </Select.Group>
10    <Select.Separator />
11    <Select.Group>
12      <Select.Item value="3">Option 3</Select.Item>
13      <Select.Item value="4">Option 4</Select.Item>
14    </Select.Group>
15  </Select.Content>

Accessibility

The Select component follows WAI-ARIA guidelines:

  • Trigger has role combobox
  • Content has role listbox
  • Items have role option
  • ARIA labels and descriptions