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.Label />
5  <Select.Trigger>
6    <Select.Value />
7  </Select.Trigger>
8  <Select.Content>
9    <Select.Empty />
10    <Select.Group>
11      <Select.GroupLabel />
12      <Select.Item />
13    </Select.Group>
14    <Select.Separator />
15  </Select.Content>
16</Select>

Usage

Appearance first, meaning size and variant, then how many items can be chosen, and who owns the value.

Basic Select

A trigger and a list of items. Select.Value renders the current selection in the trigger.

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

Pass leadingIcon to Select.Item to show an icon before the item text.

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>

Label

Select.Label renders a visible label linked to the trigger. Clicking it focuses the trigger.

1<Flex direction="column" gap={2}>
2  <Select>
3    <Select.Label>Fruit</Select.Label>
4    <Select.Trigger>
5      <Select.Value placeholder="Select a fruit" />
6    </Select.Trigger>
7    <Select.Content>
8      <Select.Item value="apple">Apple</Select.Item>
9      <Select.Item value="banana">Banana</Select.Item>
10    </Select.Content>
11  </Select>
12</Flex>

Size

Two sizes. medium is the default; small fits toolbars and table filters.

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="Medium select" />
14    </Select.Trigger>

Variant

outline (the default) draws a bordered control. text removes the border for use inside a toolbar or beside other text.

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

Select.Separator draws a rule between groups of items.

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>

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>

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.Empty>No results</Select.Empty>
7    <Select.Group>
8      <Select.Item value="1">Option 1</Select.Item>
9      <Select.Item value="2">Option 2</Select.Item>
10    </Select.Group>
11    <Select.Separator />
12    <Select.Group>
13      <Select.Item value="3">Option 3</Select.Item>
14      <Select.Item value="4">Option 4</Select.Item>

Controlled

Pass value with onValueChange to own the selection. Do this when the value comes from a form, a URL, or another control on the page.

1(function ControlledSelect() {
2  const [fruit, setFruit] = React.useState("apple");
3

4  return (
5    <Flex direction="column" gap={5}>
6      <Select value={fruit} onValueChange={setFruit}>
7        <Select.Trigger width={200}>
8          <Select.Value />
9        </Select.Trigger>
10        <Select.Content>
11          <Select.Item value="apple">Apple</Select.Item>
12          <Select.Item value="banana">Banana</Select.Item>
13          <Select.Item value="grapes">Grapes</Select.Item>
14        </Select.Content>

API Reference

The trigger, and the parts of the list it opens.

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

Value

Shows the selected item's label and icon in the trigger, or the placeholder when no item is selected.

Prop

Type

Content

The container that holds the Select items.

Prop

Type

Set alignItemWithTrigger to open the list over the trigger, with the selected item lined up on the trigger's value. Base UI turns it off for touch input and when there is not enough space, and then places the list the normal way. side and align only apply when the list is placed the normal way.

Item

Individual clickable options within the Select.

Prop

Type

Group

A way to group related Select items together.

Prop

Type

Label

A visible label linked to the trigger.

Prop

Type

GroupLabel

The label of a Select.Group. Use it only inside Select.Group.

Prop

Type

Empty

Shows its content when the list has no items, or when no item matches the search in autocomplete mode. Place it inside Select.Content.

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-labelThe label linked to 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-group-labelThe label of a group
select-emptyThe message shown when the list has no matching item
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

Accessibility

The Select component follows WAI-ARIA guidelines:

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