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.

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

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
select-triggerThe trigger button that opens the menu
select-trigger-contentFlex wrapper around the trigger's children
select-trigger-iconThe chevron dropdown icon in the trigger
select-valueThe <span> (or wrapper) showing the selected value or placeholder
select-value-contentInner wrapper around a single selected value
select-value-iconLeading icon of the selected value (when set)
select-value-overflowThe "+N" overflow count for multiple values (when they don't all fit)
select-positionerThe floating positioner for the popup
select-contentThe popup container
select-searchThe search input (when autocomplete is enabled)
select-listThe scrollable list of items
select-groupA group of items
select-labelThe label of a group
select-separatorA divider between items or groups
select-itemAn individual option row
select-item-iconLeading icon on an item (when set)
select-item-textThe text label of an item

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={9}>
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