Select

A select displays a collapsible list of options and allows a user to select one of them.

Favorite Animal

label

placeholder

selectionMode

isDisabled

Example

Select.tsx

Select.css

Example

Select.tsx

Select.css

import {Select, SelectItem} from './Select';

<Select label="Favorite Animal">
  <SelectItem>Aardvark</SelectItem>
  <SelectItem>Cat</SelectItem>
  <SelectItem>Dog</SelectItem>
  <SelectItem>Kangaroo</SelectItem>
  <SelectItem>Panda</SelectItem>
  <SelectItem>Snake</SelectItem>
</Select>

Content

Select reuses the ListBox component, following the Collection Components API. It supports ListBox features such as static and dynamic collections, sections, disabled items, links, text slots, asynchronous loading, etc. See the ListBox docs for more details.

The following example shows a dynamic collection of items, grouped into sections.

Preferred fruit or vegetable

import {Select} from './Select';
import {ListBoxSection, ListBoxItem, Collection, Header} from 'react-aria-components';

function Example() {
    {name: 'Fruit', children: [
      {name: 'Apple'},
      {name: 'Banana'},
      {name: 'Orange'},
      {name: 'Honeydew'},
      {name: 'Grapes'},
      {name: 'Watermelon'},
      {name: 'Cantaloupe'},
      {name: 'Pear'}
    ]},
    {name: 'Vegetable', children: [
      {name: 'Cabbage'},
      {name: 'Broccoli'},
      {name: 'Carrots'},
      {name: 'Lettuce'},
      {name: 'Spinach'},
      {name: 'Bok Choy'},
      {name: 'Cauliflower'},
      {name: 'Potatoes'}
    ]}
  ];

  return (
    <Select label="Preferred fruit or vegetable" items={options}>
      {section => (
        <ListBoxSection id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {item => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
          </Collection>
        </ListBoxSection>
      )}
    </Select>
  );
}

Autocomplete

Select can include additional components as siblings of the ListBox. This example uses an Autocomplete with a SearchField to let the user filter the items.

Add tag...

import {Select, Label, Button, SelectValue, Popover, ListBox, ListBoxItem, Autocomplete, useFilter} from 'react-aria-components';
import {SearchField} from './SearchField';

function Example() {
  let {contains} = useFilter({sensitivity: 'base'});

  return (
    <Select>
      <Label>Add tag...</Label>
      <Button>
        <SelectValue />
        <span aria-hidden="true">▼</span>
      </Button>
      <Popover>
        <Autocomplete filter={contains}>
          <SearchField label="Search tags" autoFocus />
          <ListBox>
            <ListBoxItem>News</ListBoxItem>
            <ListBoxItem>Travel</ListBoxItem>
            <ListBoxItem>Shopping</ListBoxItem>
            <ListBoxItem>Business</ListBoxItem>
            <ListBoxItem>Entertainment</ListBoxItem>
            <ListBoxItem>Food</ListBoxItem>
            <ListBoxItem>Technology</ListBoxItem>
            <ListBoxItem>Health</ListBoxItem>
            <ListBoxItem>Science</ListBoxItem>
          </ListBox>
        </Autocomplete>
      </Popover>
    </Select>
  );
}

Value

Use the defaultValue or value prop to set the selected item. The value corresponds to the id prop of an item. When selectionMode="multiple", value and onChange accept an array. Items can be disabled with the isDisabled prop.

Pick an animal

Current selection: "bison"

selectionMode

import {Select, SelectItem} from './Select';
import {useState} from 'react';

function Example(props) {
  let [animal, setAnimal] = useState("bison");

  return (
    <div>
      <Select
        {...props}
        label="Pick an animal"
        value={animal}
        onChange={setAnimal}
      >
        <SelectItem id="koala">Koala</SelectItem>
        <SelectItem id="kangaroo">Kangaroo</SelectItem>
        <SelectItem id="platypus" isDisabled>Platypus</SelectItem>
        <SelectItem id="eagle">Bald Eagle</SelectItem>
        <SelectItem id="bison">Bison</SelectItem>
        <SelectItem id="skunk">Skunk</SelectItem>
      </Select>
      <pre style={{fontSize: 12}}>Current selection: {JSON.stringify(animal)}</pre>
    </div>
  );
}

Forms

Use the name prop to submit the id of the selected item to the server. Set the isRequired prop to validate that the user selects an option, or implement custom client or server-side validation. See the Forms guide to learn more.

import {Select, SelectItem} from './Select';
import {Button} from './Button';
import {Form} from 'react-aria-components';

<Form>
  <Select
    label="Animal"
    name="animal"
    isRequired
    description="Please select an animal.">
    <SelectItem id="aardvark">Aardvark</SelectItem>
    <SelectItem id="cat">Cat</SelectItem>
    <SelectItem id="dog">Dog</SelectItem>
    <SelectItem id="kangaroo">Kangaroo</SelectItem>
    <SelectItem id="panda">Panda</SelectItem>
    <SelectItem id="snake">Snake</SelectItem>
  </Select>
  <Button type="submit">Submit</Button>
</Form>