Apsara

Documentation

Playground

Icons

SelectupdateUPDATE

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

Usage

The Popover component provides a way to display rich content in a portal when triggered by a button. It supports accessibility features, positioning options, and customizable styling.

import { Select } from "@raystack/apsara/v1";
 
<Select>
  <Select.Trigger aria-label="Fruit selection">
    <Select.Value placeholder="Select a fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="apple">Apple</Select.Item>
    <Select.Item value="banana">Banana</Select.Item>
  </Select.Content>
</Select>;

Select Props

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

PropTypeDefault
multiple
boolean
false
autocomplete
boolean
false
autocompleteMode
"auto" | "manual"
"auto"
searchValue
string
-
defaultSearchValue
string
-
onSearch
(value: string) => void
-

Select.Trigger Props

The button that triggers the Select.

PropTypeDefault
size
"small" | "medium"
-
variant
"default" | "filter"
-
iconProps
Record<string, any>
-
ariaLabel
string
-
ariaDescribedby
string
-
ariaRequired
boolean
-
ariaInvalid
boolean
-

Select.Content Props

The container that holds the Select items.

PropTypeDefault
searchPlaceholder
string
"Search..."
position
"item-aligned" | "popper"
"popper"
className
string
-

Select.Item Props

Individual clickable options within the Select.

PropTypeDefault
value
string
-
className
string
-

Select.Group

A way to group related Select items together.

PropTypeDefault
className
string
-
asChild
boolean
-

Select.Label

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

PropTypeDefault
className
string
-
asChild
boolean
-

Select.Separator

Visual divider between Select items or groups.

PropTypeDefault
className
string
-
asChild
boolean
-

Examples

Basic Select

<Select>
  <Select.Trigger aria-label="Fruit selection">
    <Select.Value placeholder="Select a fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="apple">Apple</Select.Item>
    <Select.Item value="banana">Banana</Select.Item>
  </Select.Content>
</Select>

Icon

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

<Select>
  <Select.Trigger aria-label="Fruit selection">
    <Select.Value placeholder="Select a fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="apple" leadingIcon={<Info size={16} />}>
      Apple
    </Select.Item>
    <Select.Item value="banana" leadingIcon={<X size={16} />}>
      Banana
    </Select.Item>
    <Select.Item value="grape" leadingIcon={<Home size={16} />}>
      Grape
    </Select.Item>
    <Select.Item value="Orange" leadingIcon={<Laugh size={16} />}>
      Orange
    </Select.Item>
  </Select.Content>
</Select>

Size

<Flex align="center" gap="large">
  <Select>
    <Select.Trigger size="small">
      <Select.Value placeholder="Small select" />
    </Select.Trigger>
    <Select.Content>
      <Select.Item value="1">Option 1</Select.Item>
      <Select.Item value="2">Option 2</Select.Item>
    </Select.Content>
  </Select>
  <Select>
    <Select.Trigger>
      <Select.Value placeholder="Small select" />
    </Select.Trigger>
    <Select.Content>
      <Select.Item value="1">Option 1</Select.Item>
      <Select.Item value="2">Option 2</Select.Item>
    </Select.Content>
  </Select>
</Flex>

Variant

<Select>
  <Select.Trigger>
    <Select.Value placeholder="Select..." />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="all">All</Select.Item>
    <Select.Item value="active">Active</Select.Item>
    <Select.Item value="inactive">Inactive</Select.Item>
  </Select.Content>
</Select>

With Separator

<Select>
  <Select.Trigger>
    <Select.Value placeholder="Select..." />
  </Select.Trigger>
  <Select.Content>
    <Select.Group>
      <Select.Item value="1">Option 1</Select.Item>
      <Select.Item value="2">Option 2</Select.Item>
    </Select.Group>
    <Select.Separator />
    <Select.Group>
      <Select.Item value="3">Option 3</Select.Item>
      <Select.Item value="4">Option 4</Select.Item>
    </Select.Group>
  </Select.Content>
</Select>

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.

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

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.

<Select autocomplete>
  <Select.Trigger>
    <Select.Value placeholder="Select..." />
  </Select.Trigger>
  <Select.Content>
    <Select.Group>
      <Select.Item value="1">Option 1</Select.Item>
      <Select.Item value="2">Option 2</Select.Item>
    </Select.Group>
    <Select.Separator />
    <Select.Group>
      <Select.Item value="3">Option 3</Select.Item>
      <Select.Item value="4">Option 4</Select.Item>
    </Select.Group>
  </Select.Content>
</Select>

Accessibility

The Select component follows WAI-ARIA guidelines:

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

Previous

Search

Next

Separator

On this page