Select

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

install	`yarn add react-aria-components`
version	1.4.0
usage	`import {Select} from 'react-aria-components'`

View ARIA pattern

W3C

Example#

import {Button, Label, ListBox, ListBoxItem, Popover, Select, SelectValue} from 'react-aria-components';

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

import {
  Button,
  Label,
  ListBox,
  ListBoxItem,
  Popover,
  Select,
  SelectValue
} from 'react-aria-components';

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

import {
  Button,
  Label,
  ListBox,
  ListBoxItem,
  Popover,
  Select,
  SelectValue
} from 'react-aria-components';

<Select>
  <Label>
    Favorite Animal
  </Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">
      ▼
    </span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>
        Aardvark
      </ListBoxItem>
      <ListBoxItem>
        Cat
      </ListBoxItem>
      <ListBoxItem>
        Dog
      </ListBoxItem>
      <ListBoxItem>
        Kangaroo
      </ListBoxItem>
      <ListBoxItem>
        Panda
      </ListBoxItem>
      <ListBoxItem>
        Snake
      </ListBoxItem>
    </ListBox>
  </Popover>
</Select>

Show CSS

@import "@react-aria/example-theme";

.react-aria-Select {
  color: var(--text-color);

  .react-aria-Button {
    box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
    border-radius: 6px;
    font-size: 1.072rem;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    display: flex;
    align-items: center;
    max-width: 250px;

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -1px;
    }
  }

  .react-aria-SelectValue {
    &[data-placeholder] {
      font-style: italic;
      color: var(--text-color-placeholder);
    }
  }

  span[aria-hidden] {
    width: 1.5rem;
    line-height: 1.375rem;
    margin-left: 1rem;
    padding: 1px;
    background: var(--highlight-background);
    color: var(--highlight-foreground);
    forced-color-adjust: none;
    border-radius: 4px;
    font-size: 0.857rem;
  }
}

.react-aria-Popover[data-trigger=Select] {
  min-width: var(--trigger-width);

  .react-aria-ListBox {
    display: block;
    width: unset;
    max-height: inherit;
    min-height: unset;
    border: none;

    .react-aria-Header {
      padding-left: 1.571rem;
    }
  }

  .react-aria-ListBoxItem {
    padding: 0.286rem 0.571rem 0.286rem 1.571rem;

    &[data-focus-visible] {
      outline: none;
    }

    &[data-selected] {
      font-weight: 600;
      background: unset;
      color: var(--text-color);

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
    }
  }
}

@import "@react-aria/example-theme";

.react-aria-Select {
  color: var(--text-color);

  .react-aria-Button {
    box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
    border-radius: 6px;
    font-size: 1.072rem;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    display: flex;
    align-items: center;
    max-width: 250px;

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -1px;
    }
  }

  .react-aria-SelectValue {
    &[data-placeholder] {
      font-style: italic;
      color: var(--text-color-placeholder);
    }
  }

  span[aria-hidden] {
    width: 1.5rem;
    line-height: 1.375rem;
    margin-left: 1rem;
    padding: 1px;
    background: var(--highlight-background);
    color: var(--highlight-foreground);
    forced-color-adjust: none;
    border-radius: 4px;
    font-size: 0.857rem;
  }
}

.react-aria-Popover[data-trigger=Select] {
  min-width: var(--trigger-width);

  .react-aria-ListBox {
    display: block;
    width: unset;
    max-height: inherit;
    min-height: unset;
    border: none;

    .react-aria-Header {
      padding-left: 1.571rem;
    }
  }

  .react-aria-ListBoxItem {
    padding: 0.286rem 0.571rem 0.286rem 1.571rem;

    &[data-focus-visible] {
      outline: none;
    }

    &[data-selected] {
      font-weight: 600;
      background: unset;
      color: var(--text-color);

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
    }
  }
}

@import "@react-aria/example-theme";

.react-aria-Select {
  color: var(--text-color);

  .react-aria-Button {
    box-shadow: 0 1px 2px rgba(0 0 0 / 0.1);
    border-radius: 6px;
    font-size: 1.072rem;
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    display: flex;
    align-items: center;
    max-width: 250px;

    &[data-focus-visible] {
      outline: 2px solid var(--focus-ring-color);
      outline-offset: -1px;
    }
  }

  .react-aria-SelectValue {
    &[data-placeholder] {
      font-style: italic;
      color: var(--text-color-placeholder);
    }
  }

  span[aria-hidden] {
    width: 1.5rem;
    line-height: 1.375rem;
    margin-left: 1rem;
    padding: 1px;
    background: var(--highlight-background);
    color: var(--highlight-foreground);
    forced-color-adjust: none;
    border-radius: 4px;
    font-size: 0.857rem;
  }
}

.react-aria-Popover[data-trigger=Select] {
  min-width: var(--trigger-width);

  .react-aria-ListBox {
    display: block;
    width: unset;
    max-height: inherit;
    min-height: unset;
    border: none;

    .react-aria-Header {
      padding-left: 1.571rem;
    }
  }

  .react-aria-ListBoxItem {
    padding: 0.286rem 0.571rem 0.286rem 1.571rem;

    &[data-focus-visible] {
      outline: none;
    }

    &[data-selected] {
      font-weight: 600;
      background: unset;
      color: var(--text-color);

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);
    }
  }
}

Features#

A select can be built using the <select> and <option> HTML elements, but this is not possible to style consistently cross browser, especially the options. Select helps achieve accessible select components that can be styled as needed without compromising on high quality interactions.

Flexible – Support for controlled and uncontrolled state, async loading, disabled items, validation, sections, complex items, and more.
Keyboard navigation – Select can be opened and navigated using the arrow keys, along with page up/down, home/end, etc. Auto scrolling, and typeahead both in the listbox and on the button, are supported as well.
Accessible – Follows the ARIA listbox pattern, with support for items and sections, and slots for label and description elements within each item for improved screen reader announcement.
HTML form integration – A visually hidden <select> element is included to enable HTML form integration, autofill, and mobile form navigation via the software keyboard.
Validation – Support for native HTML constraint validation with customizable UI, custom validation functions, and server-side validation errors.
Styleable – Items include builtin states for styling, such as hover, press, focus, selected, and disabled.

Anatomy#

A select consists of a label, a button which displays a selected value, and a listbox, displayed in a popover. Users can click, touch, or use the keyboard on the button to open the listbox popover.

Select also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages. These are linked with the input via the aria-describedby attribute.

import {Button, FieldError, Header, Label, ListBox, ListBoxItem, Popover, Section, Select, SelectValue, Text} from 'react-aria-components';

<Select>
  <Label />
  <Button>
    <SelectValue />
  </Button>
  <Text slot="description" />
  <FieldError />
  <Popover>
    <ListBox>
      <ListBoxItem>
        <Text slot="label" />
        <Text slot="description" />
      </ListBoxItem>
      <Section>
        <Header />
        <ListBoxItem />
      </Section>
    </ListBox>
  </Popover>
</Select>

import {
  Button,
  FieldError,
  Header,
  Label,
  ListBox,
  ListBoxItem,
  Popover,
  Section,
  Select,
  SelectValue,
  Text
} from 'react-aria-components';

<Select>
  <Label />
  <Button>
    <SelectValue />
  </Button>
  <Text slot="description" />
  <FieldError />
  <Popover>
    <ListBox>
      <ListBoxItem>
        <Text slot="label" />
        <Text slot="description" />
      </ListBoxItem>
      <Section>
        <Header />
        <ListBoxItem />
      </Section>
    </ListBox>
  </Popover>
</Select>

import {
  Button,
  FieldError,
  Header,
  Label,
  ListBox,
  ListBoxItem,
  Popover,
  Section,
  Select,
  SelectValue,
  Text
} from 'react-aria-components';

<Select>
  <Label />
  <Button>
    <SelectValue />
  </Button>
  <Text slot="description" />
  <FieldError />
  <Popover>
    <ListBox>
      <ListBoxItem>
        <Text slot="label" />
        <Text slot="description" />
      </ListBoxItem>
      <Section>
        <Header />
        <ListBoxItem />
      </Section>
    </ListBox>
  </Popover>
</Select>

If a select does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify it to assistive technology.

Concepts#

Select makes use of the following concepts:

Collections

Defining collections of items, async loading, and updating items over time.

Selection

Interactions and data structures to represent selection.

Forms

Validating and submitting form data, and integrating with form libraries.

Composed components#

A Select uses the following components, which may also be used standalone or reused in other components.

Label

A label provides context for an input element.

Button

A button allows a user to perform an action.

Popover

A popover displays content in context with a trigger element.

ListBox

A listbox allows a user to select one or more options from a list.

Examples#

Status Select

An issue status dropdown styled with Tailwind CSS.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Reusable wrappers#

If you will use a Select in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps Select and all of its children together into a single component which accepts a label prop and children, which are passed through to the right places. It also shows how to use the description slot to render help text, and FieldError component to render validation errors. The Item component is also wrapped to apply class names based on the current state, as described in the styling section.

import type {ListBoxItemProps, SelectProps, ValidationResult} from 'react-aria-components';
import {FieldError, Text} from 'react-aria-components';

interface MySelectProps<T extends object>
  extends Omit<SelectProps<T>, 'children'> {
  label?: string;
  description?: string;
  errorMessage?: string | ((validation: ValidationResult) => string);
  items?: Iterable<T>;
  children: React.ReactNode | ((item: T) => React.ReactNode);
}

export function MySelect<T extends object>(
  { label, description, errorMessage, children, items, ...props }:
    MySelectProps<T>
) {
  return (
    <Select {...props}>
      <Label>{label}</Label>
      <Button>
        <SelectValue />
        <span aria-hidden="true">▼</span>
      </Button>
      {description && <Text slot="description">{description}</Text>}
      <FieldError>{errorMessage}</FieldError>
      <Popover>
        <ListBox items={items}>
          {children}
        </ListBox>
      </Popover>
    </Select>
  );
}

export function MyItem(props: ListBoxItemProps) {
  return (
    <ListBoxItem
      {...props}
      className={({ isFocused, isSelected }) =>
        `my-item ${isFocused ? 'focused' : ''} ${isSelected ? 'selected' : ''}`}
    />
  );
}

<MySelect label="Ice cream flavor">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MySelect>

import type {
  ListBoxItemProps,
  SelectProps,
  ValidationResult
} from 'react-aria-components';
import {FieldError, Text} from 'react-aria-components';

interface MySelectProps<T extends object>
  extends Omit<SelectProps<T>, 'children'> {
  label?: string;
  description?: string;
  errorMessage?:
    | string
    | ((validation: ValidationResult) => string);
  items?: Iterable<T>;
  children:
    | React.ReactNode
    | ((item: T) => React.ReactNode);
}

export function MySelect<T extends object>(
  {
    label,
    description,
    errorMessage,
    children,
    items,
    ...props
  }: MySelectProps<T>
) {
  return (
    <Select {...props}>
      <Label>{label}</Label>
      <Button>
        <SelectValue />
        <span aria-hidden="true">▼</span>
      </Button>
      {description && (
        <Text slot="description">{description}</Text>
      )}
      <FieldError>{errorMessage}</FieldError>
      <Popover>
        <ListBox items={items}>
          {children}
        </ListBox>
      </Popover>
    </Select>
  );
}

export function MyItem(props: ListBoxItemProps) {
  return (
    <ListBoxItem
      {...props}
      className={({ isFocused, isSelected }) =>
        `my-item ${isFocused ? 'focused' : ''} ${
          isSelected ? 'selected' : ''
        }`}
    />
  );
}

<MySelect label="Ice cream flavor">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MySelect>

import type {
  ListBoxItemProps,
  SelectProps,
  ValidationResult
} from 'react-aria-components';
import {
  FieldError,
  Text
} from 'react-aria-components';

interface MySelectProps<
  T extends object
> extends
  Omit<
    SelectProps<T>,
    'children'
  > {
  label?: string;
  description?: string;
  errorMessage?:
    | string
    | ((
      validation:
        ValidationResult
    ) => string);
  items?: Iterable<T>;
  children:
    | React.ReactNode
    | ((
      item: T
    ) =>
      React.ReactNode);
}

export function MySelect<
  T extends object
>({
  label,
  description,
  errorMessage,
  children,
  items,
  ...props
}: MySelectProps<T>) {
  return (
    <Select {...props}>
      <Label>
        {label}
      </Label>
      <Button>
        <SelectValue />
        <span aria-hidden="true">
          ▼
        </span>
      </Button>
      {description && (
        <Text slot="description">
          {description}
        </Text>
      )}
      <FieldError>
        {errorMessage}
      </FieldError>
      <Popover>
        <ListBox
          items={items}
        >
          {children}
        </ListBox>
      </Popover>
    </Select>
  );
}

export function MyItem(
  props: ListBoxItemProps
) {
  return (
    <ListBoxItem
      {...props}
      className={(
        {
          isFocused,
          isSelected
        }
      ) =>
        `my-item ${
          isFocused
            ? 'focused'
            : ''
        } ${
          isSelected
            ? 'selected'
            : ''
        }`}
    />
  );
}

<MySelect label="Ice cream flavor">
  <MyItem>
    Chocolate
  </MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>
    Strawberry
  </MyItem>
  <MyItem>
    Vanilla
  </MyItem>
</MySelect>

Show CSS

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;
    background: none;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    background: Highlight;
    color: HighlightText;
  }
}

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;
    background: none;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    background: Highlight;
    color: HighlightText;
  }
}

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--text-color);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;
    background: none;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

@media (forced-colors: active) {
  .my-item.focused {
    background: Highlight;
    color: HighlightText;
  }
}

Content#

Select follows the Collection Components API, accepting both static and dynamic collections. The examples above show static collections, which can be used when the full list of options is known ahead of time. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time.

As seen below, an iterable list of options is passed to the Select using the items prop. Each item accepts an id prop, which is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property, as shown in the example below, then this is used automatically and an id prop is not required.

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];

  return (
    <MySelect label="Pick an engineering major" items={options}>
      {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
    </MySelect>
  );
}

function Example() {
  let options = [
    { id: 1, name: 'Aerospace' },
    { id: 2, name: 'Mechanical' },
    { id: 3, name: 'Civil' },
    { id: 4, name: 'Biomedical' },
    { id: 5, name: 'Nuclear' },
    { id: 6, name: 'Industrial' },
    { id: 7, name: 'Chemical' },
    { id: 8, name: 'Agricultural' },
    { id: 9, name: 'Electrical' }
  ];

  return (
    <MySelect
      label="Pick an engineering major"
      items={options}
    >
      {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
    </MySelect>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name: 'Aerospace'
    },
    {
      id: 2,
      name: 'Mechanical'
    },
    {
      id: 3,
      name: 'Civil'
    },
    {
      id: 4,
      name: 'Biomedical'
    },
    {
      id: 5,
      name: 'Nuclear'
    },
    {
      id: 6,
      name: 'Industrial'
    },
    {
      id: 7,
      name: 'Chemical'
    },
    {
      id: 8,
      name:
        'Agricultural'
    },
    {
      id: 9,
      name: 'Electrical'
    }
  ];

  return (
    <MySelect
      label="Pick an engineering major"
      items={options}
    >
      {(item) => (
        <ListBoxItem>
          {item.name}
        </ListBoxItem>
      )}
    </MySelect>
  );
}

Selection#

Setting a selected option can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the id prop of an item. When Select is used with a dynamic collection as described above, the id of each item is derived from the data. See the Selection guide for more details.

import type {Key} from 'react-aria-components';

function Example() {
  let options = [
    {name: 'Koala'},
    {name: 'Kangaroo'},
    {name: 'Platypus'},
    {name: 'Bald Eagle'},
    {name: 'Bison'},
    {name: 'Skunk'}
  ];
  let [animal, setAnimal] = React.useState<Key>("Bison");

  return (
    <MySelect
      label="Pick an animal (controlled)"
      items={options}
      selectedKey={animal}
      onSelectionChange={selected => setAnimal(selected)}>
      {item => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
    </MySelect>
  );
}

import type {Key} from 'react-aria-components';

function Example() {
  let options = [
    { name: 'Koala' },
    { name: 'Kangaroo' },
    { name: 'Platypus' },
    { name: 'Bald Eagle' },
    { name: 'Bison' },
    { name: 'Skunk' }
  ];
  let [animal, setAnimal] = React.useState<Key>('Bison');

  return (
    <MySelect
      label="Pick an animal (controlled)"
      items={options}
      selectedKey={animal}
      onSelectionChange={(selected) => setAnimal(selected)}
    >
      {(item) => (
        <ListBoxItem id={item.name}>
          {item.name}
        </ListBoxItem>
      )}
    </MySelect>
  );
}

import type {Key} from 'react-aria-components';

function Example() {
  let options = [
    { name: 'Koala' },
    { name: 'Kangaroo' },
    { name: 'Platypus' },
    {
      name: 'Bald Eagle'
    },
    { name: 'Bison' },
    { name: 'Skunk' }
  ];
  let [
    animal,
    setAnimal
  ] = React.useState<
    Key
  >('Bison');

  return (
    <MySelect
      label="Pick an animal (controlled)"
      items={options}
      selectedKey={animal}
      onSelectionChange={(selected) =>
        setAnimal(
          selected
        )}
    >
      {(item) => (
        <ListBoxItem
          id={item.name}
        >
          {item.name}
        </ListBoxItem>
      )}
    </MySelect>
  );
}

HTML forms#

Select supports the name prop for integration with HTML forms. The id of the selected item will be submitted to the server.

<MySelect
  label="Favorite Animal"
  name="favoriteAnimalId">
  <ListBoxItem id="panda">Panda</ListBoxItem>
  <ListBoxItem id="cat">Cat</ListBoxItem>
  <ListBoxItem id="dog">Dog</ListBoxItem>
</MySelect>

<MySelect
  label="Favorite Animal"
  name="favoriteAnimalId">
  <ListBoxItem id="panda">Panda</ListBoxItem>
  <ListBoxItem id="cat">Cat</ListBoxItem>
  <ListBoxItem id="dog">Dog</ListBoxItem>
</MySelect>

<MySelect
  label="Favorite Animal"
  name="favoriteAnimalId">
  <ListBoxItem id="panda">
    Panda
  </ListBoxItem>
  <ListBoxItem id="cat">
    Cat
  </ListBoxItem>
  <ListBoxItem id="dog">
    Dog
  </ListBoxItem>
</MySelect>

Links#

By default, interacting with an item in a Select triggers onSelectionChange. Alternatively, items may be links to another page or website. This can be achieved by passing the href prop to the <ListBoxItem> component. Link items in a Select are not selectable.

<MySelect label="Project">
  <ListBoxItem href="https://example.com/" target="_blank">
    Create new…
  </ListBoxItem>
  <ListBoxItem>Proposal</ListBoxItem>
  <ListBoxItem>Budget</ListBoxItem>
  <ListBoxItem>Onboarding</ListBoxItem>
</MySelect>

<MySelect label="Project">
  <ListBoxItem href="https://example.com/" target="_blank">
    Create new…
  </ListBoxItem>
  <ListBoxItem>Proposal</ListBoxItem>
  <ListBoxItem>Budget</ListBoxItem>
  <ListBoxItem>Onboarding</ListBoxItem>
</MySelect>

<MySelect label="Project">
  <ListBoxItem
    href="https://example.com/"
    target="_blank"
  >
    Create new…
  </ListBoxItem>
  <ListBoxItem>
    Proposal
  </ListBoxItem>
  <ListBoxItem>
    Budget
  </ListBoxItem>
  <ListBoxItem>
    Onboarding
  </ListBoxItem>
</MySelect>

Client side routing#

The <ListBoxItem> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Sections#

Select supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element. A <Header> element may also be included to label the section.

Static items#

import {Section, Header} from 'react-aria-components';

<MySelect label="Preferred fruit or vegetable">
  <Section>
    <Header>Fruit</Header>
    <ListBoxItem id="Apple">Apple</ListBoxItem>
    <ListBoxItem id="Banana">Banana</ListBoxItem>
    <ListBoxItem id="Orange">Orange</ListBoxItem>
    <ListBoxItem id="Honeydew">Honeydew</ListBoxItem>
    <ListBoxItem id="Grapes">Grapes</ListBoxItem>
    <ListBoxItem id="Watermelon">Watermelon</ListBoxItem>
    <ListBoxItem id="Cantaloupe">Cantaloupe</ListBoxItem>
    <ListBoxItem id="Pear">Pear</ListBoxItem>
  </Section>
  <Section>
    <Header>Vegetable</Header>
    <ListBoxItem id="Cabbage">Cabbage</ListBoxItem>
    <ListBoxItem id="Broccoli">Broccoli</ListBoxItem>
    <ListBoxItem id="Carrots">Carrots</ListBoxItem>
    <ListBoxItem id="Lettuce">Lettuce</ListBoxItem>
    <ListBoxItem id="Spinach">Spinach</ListBoxItem>
    <ListBoxItem id="Bok Choy">Bok Choy</ListBoxItem>
    <ListBoxItem id="Cauliflower">Cauliflower</ListBoxItem>
    <ListBoxItem id="Potatoes">Potatoes</ListBoxItem>
  </Section>
</MySelect>

import {Section, Header} from 'react-aria-components';

<MySelect label="Preferred fruit or vegetable">
  <Section>
    <Header>Fruit</Header>
    <ListBoxItem id="Apple">Apple</ListBoxItem>
    <ListBoxItem id="Banana">Banana</ListBoxItem>
    <ListBoxItem id="Orange">Orange</ListBoxItem>
    <ListBoxItem id="Honeydew">Honeydew</ListBoxItem>
    <ListBoxItem id="Grapes">Grapes</ListBoxItem>
    <ListBoxItem id="Watermelon">Watermelon</ListBoxItem>
    <ListBoxItem id="Cantaloupe">Cantaloupe</ListBoxItem>
    <ListBoxItem id="Pear">Pear</ListBoxItem>
  </Section>
  <Section>
    <Header>Vegetable</Header>
    <ListBoxItem id="Cabbage">Cabbage</ListBoxItem>
    <ListBoxItem id="Broccoli">Broccoli</ListBoxItem>
    <ListBoxItem id="Carrots">Carrots</ListBoxItem>
    <ListBoxItem id="Lettuce">Lettuce</ListBoxItem>
    <ListBoxItem id="Spinach">Spinach</ListBoxItem>
    <ListBoxItem id="Bok Choy">Bok Choy</ListBoxItem>
    <ListBoxItem id="Cauliflower">Cauliflower</ListBoxItem>
    <ListBoxItem id="Potatoes">Potatoes</ListBoxItem>
  </Section>
</MySelect>

import {
  Header,
  Section
} from 'react-aria-components';

<MySelect label="Preferred fruit or vegetable">
  <Section>
    <Header>
      Fruit
    </Header>
    <ListBoxItem id="Apple">
      Apple
    </ListBoxItem>
    <ListBoxItem id="Banana">
      Banana
    </ListBoxItem>
    <ListBoxItem id="Orange">
      Orange
    </ListBoxItem>
    <ListBoxItem id="Honeydew">
      Honeydew
    </ListBoxItem>
    <ListBoxItem id="Grapes">
      Grapes
    </ListBoxItem>
    <ListBoxItem id="Watermelon">
      Watermelon
    </ListBoxItem>
    <ListBoxItem id="Cantaloupe">
      Cantaloupe
    </ListBoxItem>
    <ListBoxItem id="Pear">
      Pear
    </ListBoxItem>
  </Section>
  <Section>
    <Header>
      Vegetable
    </Header>
    <ListBoxItem id="Cabbage">
      Cabbage
    </ListBoxItem>
    <ListBoxItem id="Broccoli">
      Broccoli
    </ListBoxItem>
    <ListBoxItem id="Carrots">
      Carrots
    </ListBoxItem>
    <ListBoxItem id="Lettuce">
      Lettuce
    </ListBoxItem>
    <ListBoxItem id="Spinach">
      Spinach
    </ListBoxItem>
    <ListBoxItem id="Bok Choy">
      Bok Choy
    </ListBoxItem>
    <ListBoxItem id="Cauliflower">
      Cauliflower
    </ListBoxItem>
    <ListBoxItem id="Potatoes">
      Potatoes
    </ListBoxItem>
  </Section>
</MySelect>

Dynamic items#

Sections used with dynamic items are populated from a hierarchical data structure. Similarly to the props on Select, <Section> takes an array of data using the items prop. If the section also has a header, the Collection component can be used to render the child items.

import {Collection} from 'react-aria-components';

function Example() {
  let options = [
    {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 (
    <MySelect label="Preferred fruit or vegetable" items={options}>
      {section => (
        <Section id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {item => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
          </Collection>
        </Section>
      )}
    </MySelect>
  );
}

import {Collection} from 'react-aria-components';

function Example() {
  let options = [
    {
      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 (
    <MySelect
      label="Preferred fruit or vegetable"
      items={options}
    >
      {(section) => (
        <Section id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {(item) => (
              <ListBoxItem id={item.name}>
                {item.name}
              </ListBoxItem>
            )}
          </Collection>
        </Section>
      )}
    </MySelect>
  );
}

import {Collection} from 'react-aria-components';

function Example() {
  let options = [
    {
      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 (
    <MySelect
      label="Preferred fruit or vegetable"
      items={options}
    >
      {(section) => (
        <Section
          id={section
            .name}
        >
          <Header>
            {section
              .name}
          </Header>
          <Collection
            items={section
              .children}
          >
            {(item) => (
              <ListBoxItem
                id={item
                  .name}
              >
                {item
                  .name}
              </ListBoxItem>
            )}
          </Collection>
        </Section>
      )}
    </MySelect>
  );
}

Text slots#

By default, items in a Select are labeled by their text contents for accessibility. ListBoxItems also support the "label" and "description" slots to separate primary and secondary content, which improves screen reader announcements and can also be used for styling purposes.

Note: The ARIA spec prohibits listbox items from including interactive content such as buttons, checkboxes, etc.

import {Text} from 'react-aria-components';

<MySelect label="Permissions">
  <ListBoxItem textValue="Read">
    <Text slot="label">Read</Text>
    <Text slot="description">Read only</Text>
  </ListBoxItem>
  <ListBoxItem textValue="Write">
    <Text slot="label">Write</Text>
    <Text slot="description">Read and write only</Text>
  </ListBoxItem>
  <ListBoxItem textValue="Admin">
    <Text slot="label">Admin</Text>
    <Text slot="description">Full access</Text>
  </ListBoxItem>
</MySelect>

import {Text} from 'react-aria-components';

<MySelect label="Permissions">
  <ListBoxItem textValue="Read">
    <Text slot="label">Read</Text>
    <Text slot="description">Read only</Text>
  </ListBoxItem>
  <ListBoxItem textValue="Write">
    <Text slot="label">Write</Text>
    <Text slot="description">Read and write only</Text>
  </ListBoxItem>
  <ListBoxItem textValue="Admin">
    <Text slot="label">Admin</Text>
    <Text slot="description">Full access</Text>
  </ListBoxItem>
</MySelect>

import {Text} from 'react-aria-components';

<MySelect label="Permissions">
  <ListBoxItem textValue="Read">
    <Text slot="label">
      Read
    </Text>
    <Text slot="description">
      Read only
    </Text>
  </ListBoxItem>
  <ListBoxItem textValue="Write">
    <Text slot="label">
      Write
    </Text>
    <Text slot="description">
      Read and write
      only
    </Text>
  </ListBoxItem>
  <ListBoxItem textValue="Admin">
    <Text slot="label">
      Admin
    </Text>
    <Text slot="description">
      Full access
    </Text>
  </ListBoxItem>
</MySelect>

Show CSS

.react-aria-Select {
  .react-aria-SelectValue {
    [slot=description] {
      display: none;
    }
  }
}

.react-aria-Select {
  .react-aria-SelectValue {
    [slot=description] {
      display: none;
    }
  }
}

.react-aria-Select {
  .react-aria-SelectValue {
    [slot=description] {
      display: none;
    }
  }
}

Asynchronous loading#

This example uses the useAsyncList hook to handle asynchronous loading of data from a server. You may additionally want to display a spinner to indicate the loading state to the user.

import {useAsyncList} from 'react-stately';

interface Character {
  name: string;
}

function AsyncLoadingExample() {
  let list = useAsyncList<Character>({
    async load({ signal, filterText }) {
      let res = await fetch(
        `https://pokeapi.co/api/v2/pokemon`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results
      };
    }
  });

  return (
    <MySelect label="Pick a Pokemon" items={list.items}>
      {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
    </MySelect>
  );
}

import {useAsyncList} from 'react-stately';

interface Character {
  name: string;
}

function AsyncLoadingExample() {
  let list = useAsyncList<Character>({
    async load({ signal, filterText }) {
      let res = await fetch(
        `https://pokeapi.co/api/v2/pokemon`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results
      };
    }
  });

  return (
    <MySelect label="Pick a Pokemon" items={list.items}>
      {(item) => (
        <ListBoxItem id={item.name}>
          {item.name}
        </ListBoxItem>
      )}
    </MySelect>
  );
}

import {useAsyncList} from 'react-stately';

interface Character {
  name: string;
}

function AsyncLoadingExample() {
  let list =
    useAsyncList<
      Character
    >({
      async load(
        {
          signal,
          filterText
        }
      ) {
        let res =
          await fetch(
            `https://pokeapi.co/api/v2/pokemon`,
            { signal }
          );
        let json =
          await res
            .json();

        return {
          items:
            json.results
        };
      }
    });

  return (
    <MySelect
      label="Pick a Pokemon"
      items={list.items}
    >
      {(item) => (
        <ListBoxItem
          id={item.name}
        >
          {item.name}
        </ListBoxItem>
      )}
    </MySelect>
  );
}

Disabled#

A Select can be fully disabled using the isDisabled prop.

<MySelect label="Choose frequency" isDisabled>
  <ListBoxItem id="rarely">Rarely</ListBoxItem>
  <ListBoxItem id="sometimes">Sometimes</ListBoxItem>
  <ListBoxItem id="always">Always</ListBoxItem>
</MySelect>

<MySelect label="Choose frequency" isDisabled>
  <ListBoxItem id="rarely">Rarely</ListBoxItem>
  <ListBoxItem id="sometimes">Sometimes</ListBoxItem>
  <ListBoxItem id="always">Always</ListBoxItem>
</MySelect>

<MySelect
  label="Choose frequency"
  isDisabled
>
  <ListBoxItem id="rarely">
    Rarely
  </ListBoxItem>
  <ListBoxItem id="sometimes">
    Sometimes
  </ListBoxItem>
  <ListBoxItem id="always">
    Always
  </ListBoxItem>
</MySelect>

Show CSS

.react-aria-Select {
  .react-aria-Button {
    &[data-disabled] {
      border-color: var(--border-color-disabled);
      color: var(--text-color-disabled);
      span[aria-hidden] {
        background: var(--border-color-disabled);
        color: var(--text-color-disabled);
      }

      .react-aria-SelectValue {
        &[data-placeholder] {
          color: var(--text-color-disabled);
        }
      }
    }
  }
}

@media (forced-colors: active) {
  .react-aria-Select {
    .react-aria-Button {
      &[data-disabled] span[aria-hidden] {
        background: 0 0;
      }
    }
  }
}

.react-aria-Select {
  .react-aria-Button {
    &[data-disabled] {
      border-color: var(--border-color-disabled);
      color: var(--text-color-disabled);
      span[aria-hidden] {
        background: var(--border-color-disabled);
        color: var(--text-color-disabled);
      }

      .react-aria-SelectValue {
        &[data-placeholder] {
          color: var(--text-color-disabled);
        }
      }
    }
  }
}

@media (forced-colors: active) {
  .react-aria-Select {
    .react-aria-Button {
      &[data-disabled] span[aria-hidden] {
        background: 0 0;
      }
    }
  }
}

.react-aria-Select {
  .react-aria-Button {
    &[data-disabled] {
      border-color: var(--border-color-disabled);
      color: var(--text-color-disabled);
      span[aria-hidden] {
        background: var(--border-color-disabled);
        color: var(--text-color-disabled);
      }

      .react-aria-SelectValue {
        &[data-placeholder] {
          color: var(--text-color-disabled);
        }
      }
    }
  }
}

@media (forced-colors: active) {
  .react-aria-Select {
    .react-aria-Button {
      &[data-disabled] span[aria-hidden] {
        background: 0 0;
      }
    }
  }
}

Disabled options#

Select supports marking items as disabled using the disabledKeys prop. Each key in this list corresponds with the id prop passed to the ListBoxItem component, or automatically derived from the values passed to the items prop. See the Collections guide for more details.

Disabled items are not focusable, selectable, or keyboard navigable. The isDisabled property returned by useOption can be used to style the item appropriately.

<MySelect label="Favorite Animal" disabledKeys={['cat', 'kangaroo']}>
  <ListBoxItem id="red panda">Red Panda</ListBoxItem>
  <ListBoxItem id="cat">Cat</ListBoxItem>
  <ListBoxItem id="dog">Dog</ListBoxItem>
  <ListBoxItem id="aardvark">Aardvark</ListBoxItem>
  <ListBoxItem id="kangaroo">Kangaroo</ListBoxItem>
  <ListBoxItem id="snake">Snake</ListBoxItem>
</MySelect>

<MySelect
  label="Favorite Animal"
  disabledKeys={['cat', 'kangaroo']}
>
  <ListBoxItem id="red panda">Red Panda</ListBoxItem>
  <ListBoxItem id="cat">Cat</ListBoxItem>
  <ListBoxItem id="dog">Dog</ListBoxItem>
  <ListBoxItem id="aardvark">Aardvark</ListBoxItem>
  <ListBoxItem id="kangaroo">Kangaroo</ListBoxItem>
  <ListBoxItem id="snake">Snake</ListBoxItem>
</MySelect>

<MySelect
  label="Favorite Animal"
  disabledKeys={[
    'cat',
    'kangaroo'
  ]}
>
  <ListBoxItem id="red panda">
    Red Panda
  </ListBoxItem>
  <ListBoxItem id="cat">
    Cat
  </ListBoxItem>
  <ListBoxItem id="dog">
    Dog
  </ListBoxItem>
  <ListBoxItem id="aardvark">
    Aardvark
  </ListBoxItem>
  <ListBoxItem id="kangaroo">
    Kangaroo
  </ListBoxItem>
  <ListBoxItem id="snake">
    Snake
  </ListBoxItem>
</MySelect>

Validation#

Select supports the isRequired prop to ensure the user selects an option, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the Forms guide to learn more.

To display validation errors, add a <FieldError> element as a child of the Select. This allows you to render error messages from all of the above sources with consistent custom styles.

import {Form, FieldError} from 'react-aria-components';

<Form>
  <Select name="animal" isRequired>    <Label>Favorite Animal</Label>
    <Button>
      <SelectValue />
      <span aria-hidden="true">▼</span>
    </Button>
    <FieldError />    <Popover>
      <ListBox>
        <ListBoxItem>Aardvark</ListBoxItem>
        <ListBoxItem>Cat</ListBoxItem>
        <ListBoxItem>Dog</ListBoxItem>
        <ListBoxItem>Kangaroo</ListBoxItem>
        <ListBoxItem>Panda</ListBoxItem>
        <ListBoxItem>Snake</ListBoxItem>
      </ListBox>
    </Popover>
  </Select>
  <Button type="submit">Submit</Button>
</Form>

import {Form, FieldError} from 'react-aria-components';

<Form>
  <Select name="animal" isRequired>    <Label>Favorite Animal</Label>
    <Button>
      <SelectValue />
      <span aria-hidden="true">▼</span>
    </Button>
    <FieldError />    <Popover>
      <ListBox>
        <ListBoxItem>Aardvark</ListBoxItem>
        <ListBoxItem>Cat</ListBoxItem>
        <ListBoxItem>Dog</ListBoxItem>
        <ListBoxItem>Kangaroo</ListBoxItem>
        <ListBoxItem>Panda</ListBoxItem>
        <ListBoxItem>Snake</ListBoxItem>
      </ListBox>
    </Popover>
  </Select>
  <Button type="submit">Submit</Button>
</Form>

import {
  FieldError,
  Form
} from 'react-aria-components';

<Form>
  <Select
    name="animal"
    isRequired
  >    <Label>
      Favorite Animal
    </Label>
    <Button>
      <SelectValue />
      <span aria-hidden="true">
        ▼
      </span>
    </Button>
    <FieldError />    <Popover>
      <ListBox>
        <ListBoxItem>
          Aardvark
        </ListBoxItem>
        <ListBoxItem>
          Cat
        </ListBoxItem>
        <ListBoxItem>
          Dog
        </ListBoxItem>
        <ListBoxItem>
          Kangaroo
        </ListBoxItem>
        <ListBoxItem>
          Panda
        </ListBoxItem>
        <ListBoxItem>
          Snake
        </ListBoxItem>
      </ListBox>
    </Popover>
  </Select>
  <Button type="submit">
    Submit
  </Button>
</Form>

Show CSS

.react-aria-Select {
  .react-aria-FieldError {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

.react-aria-Select {
  .react-aria-FieldError {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

.react-aria-Select {
  .react-aria-FieldError {
    font-size: 12px;
    color: var(--invalid-color);
  }
}

By default, FieldError displays default validation messages provided by the browser. See Customizing error messages in the Forms guide to learn how to provide your own custom errors.

Description#

The description slot can be used to associate additional help text with a Select.

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <Text slot="description">Please select an animal.</Text>  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <Text slot="description">Please select an animal.</Text>  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

<Select>
  <Label>
    Favorite Animal
  </Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">
      ▼
    </span>
  </Button>
  <Text slot="description">
    Please select an
    animal.
  </Text>  <Popover>
    <ListBox>
      <ListBoxItem>
        Aardvark
      </ListBoxItem>
      <ListBoxItem>
        Cat
      </ListBoxItem>
      <ListBoxItem>
        Dog
      </ListBoxItem>
      <ListBoxItem>
        Kangaroo
      </ListBoxItem>
      <ListBoxItem>
        Panda
      </ListBoxItem>
      <ListBoxItem>
        Snake
      </ListBoxItem>
    </ListBox>
  </Popover>
</Select>

Show CSS

.react-aria-Select {
  [slot=description] {
    font-size: 12px;
  }
}

.react-aria-Select {
  [slot=description] {
    font-size: 12px;
  }
}

.react-aria-Select {
  [slot=description] {
    font-size: 12px;
  }
}

Controlled open state#

The open state of the select can be controlled via the defaultOpen and isOpen props

function Example() {
  let [open, setOpen] = React.useState(false);

  return (
    <>
      <p>Select is {open ? 'open' : 'closed'}</p>
      <MySelect label="Choose frequency" isOpen={open} onOpenChange={setOpen}>
        <ListBoxItem id="rarely">Rarely</ListBoxItem>
        <ListBoxItem id="sometimes">Sometimes</ListBoxItem>
        <ListBoxItem id="always">Always</ListBoxItem>
      </MySelect>
    </>
  );
}

function Example() {
  let [open, setOpen] = React.useState(false);

  return (
    <>
      <p>Select is {open ? 'open' : 'closed'}</p>
      <MySelect
        label="Choose frequency"
        isOpen={open}
        onOpenChange={setOpen}
      >
        <ListBoxItem id="rarely">Rarely</ListBoxItem>
        <ListBoxItem id="sometimes">Sometimes</ListBoxItem>
        <ListBoxItem id="always">Always</ListBoxItem>
      </MySelect>
    </>
  );
}

function Example() {
  let [open, setOpen] =
    React.useState(
      false
    );

  return (
    <>
      <p>
        Select is {open
          ? 'open'
          : 'closed'}
      </p>
      <MySelect
        label="Choose frequency"
        isOpen={open}
        onOpenChange={setOpen}
      >
        <ListBoxItem id="rarely">
          Rarely
        </ListBoxItem>
        <ListBoxItem id="sometimes">
          Sometimes
        </ListBoxItem>
        <ListBoxItem id="always">
          Always
        </ListBoxItem>
      </MySelect>
    </>
  );
}

Customizing SelectValue#

Select passes the rendered children of the selected item in the render props of the SelectValue as well as if the placeholder should be showing. You can use this to customize the value displayed in the Select.

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue>
      {({defaultChildren, isPlaceholder}) => {
        return isPlaceholder ? <><b>Animal</b> selection</> : defaultChildren;
      }}
    </SelectValue>    <span aria-hidden="true">▼</span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue>
      {({ defaultChildren, isPlaceholder }) => {
        return isPlaceholder
          ? (
            <>
              <b>Animal</b> selection
            </>
          )
          : defaultChildren;
      }}
    </SelectValue>    <span aria-hidden="true">▼</span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>Aardvark</ListBoxItem>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
      <ListBoxItem>Panda</ListBoxItem>
      <ListBoxItem>Snake</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

<Select>
  <Label>
    Favorite Animal
  </Label>
  <Button>
    <SelectValue>
      {(
        {
          defaultChildren,
          isPlaceholder
        }
      ) => {
        return isPlaceholder
          ? (
            <>
              <b>
                Animal
              </b>{' '}
              selection
            </>
          )
          : defaultChildren;
      }}
    </SelectValue>    <span aria-hidden="true">
      ▼
    </span>
  </Button>
  <Popover>
    <ListBox>
      <ListBoxItem>
        Aardvark
      </ListBoxItem>
      <ListBoxItem>
        Cat
      </ListBoxItem>
      <ListBoxItem>
        Dog
      </ListBoxItem>
      <ListBoxItem>
        Kangaroo
      </ListBoxItem>
      <ListBoxItem>
        Panda
      </ListBoxItem>
      <ListBoxItem>
        Snake
      </ListBoxItem>
    </ListBox>
  </Popover>
</Select>

Props#

Select#

Name	Type	Default	Description
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any. See MDN.
`name`	`string`	—	The name of the input, used when submitting an HTML form.
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validate`	`( (value: Key )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`selectedKey`	`Key \| null`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`children`	`ReactNode \| ( (values: SelectRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: SelectRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: SelectRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	Method that is called when the open state of the menu changes.
`onSelectionChange`	`( (key: Key )) => void`	Handler that is called when the selection changes.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`excludeFromTabOrder`	`boolean`	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Label#

A <Label> accepts all HTML attributes.

Button#

A <Button> accepts its contents as children. Other props such as onPress and isDisabled will be set by the Select.

Show props

Name	Type	Default	Description
`form`	`string`	—	The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document.
`formAction`	`string`	—	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
`formEncType`	`string`	—	Indicates how to encode the form data that is submitted.
`formMethod`	`string`	—	Indicates the HTTP method used to submit the form.
`formNoValidate`	`boolean`	—	Indicates that the form is not to be validated when it is submitted.
`formTarget`	`string`	—	Overrides the target attribute of the button's form owner.
`name`	`string`	—	Submitted as a pair with the button's value as part of the form data.
`value`	`string`	—	The value associated with the button's name when it's submitted with the form data.
`isPending`	`boolean`	—	Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`children`	`ReactNode \| ( (values: ButtonRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ButtonRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ButtonRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onPress`	`( (e: PressEvent )) => void`	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	Handler that is called when a key is released.
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`excludeFromTabOrder`	`boolean`	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`aria-expanded`	`boolean \| 'true' \| 'false'`	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	Indicates the current "pressed" state of toggle buttons.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

SelectValue#

The <SelectValue> component displays the current value of the select within the <Button>, or a placeholder if no value is selected.

Show props

Name	Type	Description
`children`	`ReactNode \| ( (values: SelectValueRenderProps<object> & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: SelectValueRenderProps<object> & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: SelectValueRenderProps<object> & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.

A <Popover> is a container to hold the <ListBox> suggestions for a Select. By default, it has a placement of bottom start within a <Select>, but this and other positioning properties may be customized.

Show props

Name	Type	Default	Description
`trigger`	`string`	—	The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.
`triggerRef`	`RefObject<Element \| null>`	—	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
`isEntering`	`boolean`	—	Whether the popover is currently performing an entry animation.
`isExiting`	`boolean`	—	Whether the popover is currently performing an exit animation.
`UNSTABLE_portalContainer`	`Element`	`document.body`	The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to.
`offset`	`number`	`8`	The additional offset applied along the main axis between the element and its anchor element.
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
`isNonModal`	`boolean`	—	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
`shouldCloseOnInteractOutside`	`( (element: Element )) => boolean`	—	When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
`boundaryElement`	`Element`	`document.body`	Element that that serves as the positioning boundary.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	A ref for the scrollable region within the overlay.
`shouldUpdatePosition`	`boolean`	`true`	Whether the overlay should update its position automatically.
`arrowBoundaryOffset`	`number`	`0`	The minimum distance the arrow's edge should be from the edge of the overlay element.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`children`	`ReactNode \| ( (values: PopoverRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: PopoverRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: PopoverRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	Handler that is called when the overlay's open state changes.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Sizing

Name	Type	Description
`maxHeight`	`number`	The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.

ListBox#

Within a <Select>, most <ListBox> props are set automatically. The <ListBox> defines the options to display in a Select.

Show props

Name	Type	Default	Description
`selectionBehavior`	`SelectionBehavior`	—	How multiple selection should behave in the collection.
`dragAndDropHooks`	`DragAndDropHooks`	—	The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListBox.
`renderEmptyState`	`( (props: ListBoxRenderProps )) => ReactNode`	—	Provides content to display when there are no items in the list.
`layout`	`'stack' \| 'grid'`	`'stack'`	Whether the items are arranged in a stack or grid.
`orientation`	`Orientation`	`'vertical'`	The primary orientation of the items. Usually this is the direction that the collection scrolls.
`autoFocus`	`boolean \| FocusStrategy`	—	Whether to auto focus the listbox or an option.
`shouldFocusWrap`	`boolean`	—	Whether focus should wrap around when the end/start is reached.
`items`	`Iterable<T>`	—	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	`SelectionMode`	—	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	—	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	—	The initial selected keys in the collection (uncontrolled).
`children`	`ReactNode \| ( (item: object )) => ReactNode`	—	The contents of the collection.
`dependencies`	`any[]`	—	Values that should invalidate the item cache when using dynamic collections.
`className`	`string \| ( (values: ListBoxRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ListBoxRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onAction`	`( (key: Key )) => void`	Handler that is called when a user performs an action on an item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality.
`onSelectionChange`	`( (keys: Selection )) => void`	Handler that is called when the selection changes.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.
`onScroll`	`( (e: UIEvent<Element> )) => void`	Handler that is called when a user scrolls. See MDN.

Layout

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Section#

A <Section> defines the child items for a section within a <ListBox>. It may also contain an optional <Header> element. If there is no header, then an aria-label must be provided to identify the section to assistive technologies.

Show props

Name	Type	Description
`id`	`Key`	The unique id of the section.
`value`	`object`	The object value that this section represents. When using dynamic collections, this is set automatically.
`children`	`ReactNode \| ( (item: object )) => ReactElement`	Static child items or a function to render children.
`dependencies`	`any[]`	Values that should invalidate the item cache when using dynamic collections.
`items`	`Iterable<T>`	Item objects in the section.
`className`	`string`	The CSS className for the element.
`style`	`CSSProperties`	The inline style for the element.

Accessibility

Name	Type	Description
`aria-label`	`string`	An accessibility label for the section.

A <Header> defines the title for a <Section>. It accepts all DOM attributes.

ListBoxItem#

A <ListBoxItem> defines a single option within a <ListBox>. If the children are not plain text, then the textValue prop must also be set to a plain text representation, which will be used for autocomplete in the Select.

Show props

Name	Type	Description
`id`	`Key`	The unique id of the item.
`value`	`object`	The object value that this item represents. When using dynamic collections, this is set automatically.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`isDisabled`	`boolean`	Whether the item is disabled.
`children`	`ReactNode \| ( (values: ListBoxItemRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ListBoxItemRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ListBoxItemRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.
`href`	`Href`	A URL to link to. See MDN.
`hrefLang`	`string`	Hints at the human language of the linked URL. SeeMDN.
`target`	`HTMLAttributeAnchorTarget`	The target window for the link. See MDN.
`rel`	`string`	The relationship between the linked resource and the current page. See MDN.
`download`	`boolean \| string`	Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
`ping`	`string`	A space-separated list of URLs to ping when the link is followed. See MDN.
`referrerPolicy`	`HTMLAttributeReferrerPolicy`	How much of the referrer to send when following the link. See MDN.
`routerOptions`	`RouterOptions`	Options for the configured client side router.

Events

Name	Type	Description
`onAction`	`() => void`	Handler that is called when a user performs an action on the item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality.
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Accessibility

Name	Type	Description
`aria-label`	`string`	An accessibility label for this item.

FieldError#

A <FieldError> displays validation errors.

Show props

Name	Type	Description
`children`	`ReactNode \| ( (values: FieldErrorRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: FieldErrorRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: FieldErrorRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.

Accessibility

Name	Type	Description
`id`	`string`	The element's unique identifier. See MDN.

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-Select {
  /* ... */
}

.react-aria-Select {
  /* ... */
}

.react-aria-Select {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<Select className="my-select">
  {/* ... */}
</Select>

<Select className="my-select">
  {/* ... */}
</Select>

<Select className="my-select">
  {/* ... */}
</Select>

In addition, some components support multiple UI states (e.g. pressed, hovered, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:

.react-aria-ListBoxItem[data-selected] {
  /* ... */
}

.react-aria-ListBoxItem[data-focused] {
  /* ... */
}

.react-aria-ListBoxItem[data-selected] {
  /* ... */
}

.react-aria-ListBoxItem[data-focused] {
  /* ... */
}

.react-aria-ListBoxItem[data-selected] {
  /* ... */
}

.react-aria-ListBoxItem[data-focused] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<ListBoxItem
  className={({ isSelected }) => isSelected ? 'bg-blue-400' : 'bg-gray-100'}
>
  Item
</ListBoxItem>

<ListBoxItem
  className={({ isSelected }) =>
    isSelected ? 'bg-blue-400' : 'bg-gray-100'}
>
  Item
</ListBoxItem>

<ListBoxItem
  className={(
    { isSelected }
  ) =>
    isSelected
      ? 'bg-blue-400'
      : 'bg-gray-100'}
>
  Item
</ListBoxItem>

Render props may also be used as children to alter what elements are rendered based on the current state. For example, you could render a checkmark icon when an item is selected.

<ListBoxItem>
  {({isSelected}) => (
    <>
      {isSelected && <CheckmarkIcon />}
      Item
    </>
  )}
</ListBoxItem>

<ListBoxItem>
  {({isSelected}) => (
    <>
      {isSelected && <CheckmarkIcon />}
      Item
    </>
  )}
</ListBoxItem>

<ListBoxItem>
  {(
    { isSelected }
  ) => (
    <>
      {isSelected && (
        <CheckmarkIcon />
      )}
      Item
    </>
  )}
</ListBoxItem>

The states and selectors for each component used in a Select are documented below.

Select#

A Select can be targeted with the .react-aria-Select CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`isFocused`	`[data-focused]`	Whether the select is focused, either via a mouse or keyboard.
`isFocusVisible`	`[data-focus-visible]`	Whether the select is keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the select is disabled.
`isOpen`	`[data-open]`	Whether the select is currently open.
`isInvalid`	`[data-invalid]`	Whether the select is invalid.
`isRequired`	`[data-required]`	Whether the select is required.

Label#

A Label can be targeted with the .react-aria-Label CSS selector, or by overriding with a custom className.

Button#

A Button can be targeted with the .react-aria-Button CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`isHovered`	`[data-hovered]`	Whether the button is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the button is currently in a pressed state.
`isFocused`	`[data-focused]`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`[data-focus-visible]`	Whether the button is keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the button is disabled.
`isPending`	`[data-pending]`	Whether the button is currently in a pending state.

SelectValue#

A SelectValue can be targeted with the .react-aria-SelectValue CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`isPlaceholder`	`[data-placeholder]`	Whether the value is a placeholder.
`selectedItem`	`—`	The object value of the currently selected item.
`selectedText`	`—`	The textValue of the currently selected item.

The Popover component can be targeted with the .react-aria-Popover CSS selector, or by overriding with a custom className. Note that it renders in a React Portal, so it will not appear as a descendant of the Select in the DOM. It supports the following states and render props:

Name	CSS Selector	Description
`trigger`	`[data-trigger="..."]`	The name of the component that triggered the popover, e.g. "DialogTrigger" or "ComboBox".
`placement`	`[data-placement="left \| right \| top \| bottom"]`	The placement of the popover relative to the trigger.
`isEntering`	`[data-entering]`	Whether the popover is currently entering. Use this to apply animations.
`isExiting`	`[data-exiting]`	Whether the popover is currently exiting. Use this to apply animations.

Within a Select, the popover will have the data-trigger="Select" attribute, which can be used to define select-specific styles. In addition, the --trigger-width CSS custom property will be set on the popover, which you can use to make the popover match the width of the select button.

.react-aria-Popover[data-trigger=Select] {
  width: var(--trigger-width);
}

.react-aria-Popover[data-trigger=Select] {
  width: var(--trigger-width);
}

.react-aria-Popover[data-trigger=Select] {
  width: var(--trigger-width);
}

ListBox#

A ListBox can be targeted with the .react-aria-ListBox CSS selector, or by overriding with a custom className.

Section#

A Section can be targeted with the .react-aria-Section CSS selector, or by overriding with a custom className. See sections for examples.

Header#

A Header within a Section can be targeted with the .react-aria-Header CSS selector, or by overriding with a custom className. See sections for examples.

ListBoxItem#

A ListBoxItem can be targeted with the .react-aria-ListBoxItem CSS selector, or by overriding with a custom className. It supports the following states and render props:

Name	CSS Selector	Description
`isHovered`	`[data-hovered]`	Whether the item is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the item is currently in a pressed state.
`isSelected`	`[data-selected]`	Whether the item is currently selected.
`isFocused`	`[data-focused]`	Whether the item is currently focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the item is currently keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`selectionMode`	`[data-selection-mode="single \| multiple"]`	The type of selection that is allowed in the collection.
`selectionBehavior`	`—`	The selection behavior for the collection.

Items also support two slots: a label, and a description. When provided using the <Text> element, the item will have aria-labelledby and aria-describedby attributes pointing to these slots, improving screen reader announcement. See complex items for an example.

Note that items may not contain interactive children such as buttons, as screen readers will not be able to access them.

Text#

The help text elements within a Select can be targeted with the [slot=description] and [slot=errorMessage] CSS selectors, or by adding a custom className.

FieldError#

A FieldError can be targeted with the .react-aria-FieldError CSS selector, or by overriding with a custom className. It supports the following render props:

Name	Description
`isInvalid`	Whether the input value is invalid.
`validationErrors`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	The native validation details for the input.

Advanced customization#

Composition#

If you need to customize one of the components within a Select, such as Button or ListBox, in many cases you can create a wrapper component. This lets you customize the props passed to the component.

function MyListBox(props) {
  return <ListBox {...props} className="my-listbox" />
}

function MyListBox(props) {
  return <ListBox {...props} className="my-listbox" />
}

function MyListBox(
  props
) {
  return (
    <ListBox
      {...props}
      className="my-listbox"
    />
  );
}

Contexts#

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in mergeProps).

Component	Context	Props	Ref
`Select`	`SelectContext`	`SelectProps`	`HTMLDivElement`

This example shows a FieldGroup component that renders a group of selects with a title. The entire group can be marked as disabled via the isDisabled prop, which is passed to all child selects via the SelectContext provider.

import {SelectContext} from 'react-aria-components';

interface FieldGroupProps {
  title?: string,
  children?: React.ReactNode,
  isDisabled?: boolean
}

function FieldGroup({title, children, isDisabled}: FieldGroupProps) {
  return (
    <fieldset>
      <legend>{title}</legend>
      <SelectContext.Provider value={{isDisabled}}>        {children}
      </SelectContext.Provider>
    </fieldset>
  );
}

<FieldGroup title="Filters" isDisabled>
  <MySelect label="Status" defaultSelectedKey="published">
    <ListBoxItem id="draft">Draft</ListBoxItem>
    <ListBoxItem id="published">Published</ListBoxItem>
    <ListBoxItem id="deleted">Deleted</ListBoxItem>
  </MySelect>
  <MySelect label="Author" defaultSelectedKey="emma">
    <ListBoxItem id="john">John</ListBoxItem>
    <ListBoxItem id="emma">Emma</ListBoxItem>
    <ListBoxItem id="tim">Tim</ListBoxItem>
  </MySelect>
</FieldGroup>

import {SelectContext} from 'react-aria-components';

interface FieldGroupProps {
  title?: string;
  children?: React.ReactNode;
  isDisabled?: boolean;
}

function FieldGroup(
  { title, children, isDisabled }: FieldGroupProps
) {
  return (
    <fieldset>
      <legend>{title}</legend>
      <SelectContext.Provider value={{ isDisabled }}>        {children}
      </SelectContext.Provider>
    </fieldset>
  );
}

<FieldGroup title="Filters" isDisabled>
  <MySelect label="Status" defaultSelectedKey="published">
    <ListBoxItem id="draft">Draft</ListBoxItem>
    <ListBoxItem id="published">Published</ListBoxItem>
    <ListBoxItem id="deleted">Deleted</ListBoxItem>
  </MySelect>
  <MySelect label="Author" defaultSelectedKey="emma">
    <ListBoxItem id="john">John</ListBoxItem>
    <ListBoxItem id="emma">Emma</ListBoxItem>
    <ListBoxItem id="tim">Tim</ListBoxItem>
  </MySelect>
</FieldGroup>

import {SelectContext} from 'react-aria-components';

interface FieldGroupProps {
  title?: string;
  children?:
    React.ReactNode;
  isDisabled?: boolean;
}

function FieldGroup(
  {
    title,
    children,
    isDisabled
  }: FieldGroupProps
) {
  return (
    <fieldset>
      <legend>
        {title}
      </legend>
      <SelectContext.Provider
        value={{
          isDisabled
        }}
      >        {children}
      </SelectContext.Provider>
    </fieldset>
  );
}

<FieldGroup
  title="Filters"
  isDisabled
>
  <MySelect
    label="Status"
    defaultSelectedKey="published"
  >
    <ListBoxItem id="draft">
      Draft
    </ListBoxItem>
    <ListBoxItem id="published">
      Published
    </ListBoxItem>
    <ListBoxItem id="deleted">
      Deleted
    </ListBoxItem>
  </MySelect>
  <MySelect
    label="Author"
    defaultSelectedKey="emma"
  >
    <ListBoxItem id="john">
      John
    </ListBoxItem>
    <ListBoxItem id="emma">
      Emma
    </ListBoxItem>
    <ListBoxItem id="tim">
      Tim
    </ListBoxItem>
  </MySelect>
</FieldGroup>

Show CSS

fieldset {
  padding: 1.5em;
  width: fit-content;
}

fieldset {
  padding: 1.5em;
  width: fit-content;
}

fieldset {
  padding: 1.5em;
  width: fit-content;
}

Custom children#

Select passes props to its child components, such as the label and popover, via their associated contexts. These contexts are exported so you can also consume them in your own custom components. This enables you to reuse existing components from your app or component library together with React Aria Components.

Component	Context	Props	Ref
`Label`	`LabelContext`	`LabelProps`	`HTMLLabelElement`
`Button`	`ButtonContext`	`ButtonProps`	`HTMLButtonElement`
`Popover`	`PopoverContext`	`PopoverProps`	`HTMLElement`
`ListBox`	`ListBoxContext`	`ListBoxProps`	`HTMLDivElement`
`Text`	`TextContext`	`TextProps`	`HTMLElement`

This example consumes from LabelContext in an existing styled label component to make it compatible with React Aria Components. The useContextProps hook merges the local props and ref with the ones provided via context by Select.

import type {LabelProps} from 'react-aria-components';
import {LabelContext, useContextProps} from 'react-aria-components';

const MyCustomLabel = React.forwardRef(
  (props: LabelProps, ref: React.ForwardedRef<HTMLLabelElement>) => {
    // Merge the local props and ref with the ones provided via context.
    [props, ref] = useContextProps(props, ref, LabelContext);
    // ... your existing Label component
    return <label {...props} ref={ref} />;
  }
);

import type {LabelProps} from 'react-aria-components';
import {
  LabelContext,
  useContextProps
} from 'react-aria-components';

const MyCustomLabel = React.forwardRef(
  (
    props: LabelProps,
    ref: React.ForwardedRef<HTMLLabelElement>
  ) => {
    // Merge the local props and ref with the ones provided via context.
    [props, ref] = useContextProps(
      props,
      ref,
      LabelContext
    );
    // ... your existing Label component
    return <label {...props} ref={ref} />;
  }
);

import type {LabelProps} from 'react-aria-components';
import {
  LabelContext,
  useContextProps
} from 'react-aria-components';

const MyCustomLabel =
  React.forwardRef(
    (
      props: LabelProps,
      ref:
        React.ForwardedRef<
          HTMLLabelElement
        >
    ) => {
      // Merge the local props and ref with the ones provided via context.
      [props, ref] =
        useContextProps(
          props,
          ref,
          LabelContext
        );
      // ... your existing Label component
      return (
        <label
          {...props}
          ref={ref}
        />
      );
    }
  );

Now you can use MyCustomLabel within a Select, in place of the builtin React Aria Components Label.

<Select>
  <MyCustomLabel>Name</MyCustomLabel>  {/* ... */}
</Select>

<Select>
  <MyCustomLabel>Name</MyCustomLabel>  {/* ... */}
</Select>

<Select>
  <MyCustomLabel>
    Name
  </MyCustomLabel>  {/* ... */}
</Select>

State#

Select provides an SelectState object to its children via SelectStateContext. This can be used to access and manipulate the select's state.

This example shows a SelectClearButton component that can be placed within a Select to allow the user to clear the selected item.

import {SelectStateContext} from 'react-aria-components';

function SelectClearButton() {
  let state = React.useContext(SelectStateContext);  return (
    <Button
      // Don't inherit behavior from Select.
      slot={null}
      style={{fontSize: 'small', marginTop: 6, padding: 4}}
      onPress={() => state?.setSelectedKey(null)}>
      Clear
    </Button>
  );
}

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <SelectClearButton />  <Popover>
    <ListBox>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

import {SelectStateContext} from 'react-aria-components';

function SelectClearButton() {
  let state = React.useContext(SelectStateContext);  return (
    <Button
      // Don't inherit behavior from Select.
      slot={null}
      style={{fontSize: 'small', marginTop: 6, padding: 4}}
      onPress={() => state?.setSelectedKey(null)}>
      Clear
    </Button>
  );
}

<Select>
  <Label>Favorite Animal</Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">▼</span>
  </Button>
  <SelectClearButton />  <Popover>
    <ListBox>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
  </Popover>
</Select>

import {SelectStateContext} from 'react-aria-components';

function SelectClearButton() {
  let state = React
    .useContext(
      SelectStateContext
    );  return (
    <Button
      // Don't inherit behavior from Select.
      slot={null}
      style={{
        fontSize:
          'small',
        marginTop: 6,
        padding: 4
      }}
      onPress={() =>
        state
          ?.setSelectedKey(
            null
          )}
    >
      Clear
    </Button>
  );
}

<Select>
  <Label>
    Favorite Animal
  </Label>
  <Button>
    <SelectValue />
    <span aria-hidden="true">
      ▼
    </span>
  </Button>
  <SelectClearButton />  <Popover>
    <ListBox>
      <ListBoxItem>
        Cat
      </ListBoxItem>
      <ListBoxItem>
        Dog
      </ListBoxItem>
      <ListBoxItem>
        Kangaroo
      </ListBoxItem>
    </ListBox>
  </Popover>
</Select>

Hooks#

If you need to customize things even further, such as accessing internal state, intercepting events, or customizing the DOM structure, you can drop down to the lower level Hook-based API. See useSelect for more details.

Accessibility#

False positives#

Select may trigger a known accessibility false positive from automated accessibility testing tools. This is because we include a visually hidden select element alongside the Select to specifically aid with browser form autocomplete and hide it from screen readers via aria-hidden since users don't need to interact with the hidden select. We manage focus internally so that focusing this hidden select will always shift focus to the Select's trigger button instead. Automated accessibility testing tools have no way of knowing that we manage the focus in this way and thus throw this false positive.

To facilitate the suppression of this false positive, the data-a11y-ignore="aria-hidden-focus" data attribute is automatically applied to the problematic element and references the relevant AXE rule. Please use this data attribute to target the problematic element and exclude it from your automated accessibility tests as shown here.

A RouterProvider accepts a navigate function from a framework or client side router, and provides it to all nested React Aria links to enable client side navigation.

Name	Type	Description
`navigate`	`( (path: Href, , routerOptions: RouterOptions \| \| undefined )) => void`
`children`	`ReactNode`
`useHref`	`( (href: Href )) => string`

RouterConfig extends {href: any
} ? H : string

RouterConfig extends {routerOptions: any
} ? O : never

A Collection renders a list of items, automatically managing caching and keys.

Name	Type	Description
`items`	`Iterable<object>`	Item objects in the collection.
`children`	`ReactNode \| ( (item: object )) => ReactNode`	The contents of the collection.
`dependencies`	`any[]`	Values that should invalidate the item cache when using dynamic collections.
`idScope`	`Key`	A scope to prepend to all child item ids to ensure they are unique.
`addIdAndValue`	`boolean`	Whether to add `id` and `value` props to all child items.

string | number

string | string[]

Name	Type	Description
`isFocused`	`boolean`	Whether the select is focused, either via a mouse or keyboard.
`isFocusVisible`	`boolean`	Whether the select is keyboard focused.
`isDisabled`	`boolean`	Whether the select is disabled.
`isOpen`	`boolean`	Whether the select is currently open.
`isInvalid`	`boolean`	Whether the select is invalid.
`isRequired`	`boolean`	Whether the select is required.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`isHovered`	`boolean`	Whether the button is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the button is currently in a pressed state.
`isFocused`	`boolean`	Whether the button is focused, either via a mouse or keyboard.
`isFocusVisible`	`boolean`	Whether the button is keyboard focused.
`isDisabled`	`boolean`	Whether the button is disabled.
`isPending`	`boolean`	Whether the button is currently in a pending state.

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

Name	Type	Description
`isPlaceholder`	`boolean`	Whether the value is a placeholder.
`selectedItem`	`T \| null`	The object value of the currently selected item.
`selectedText`	`string \| null`	The textValue of the currently selected item.

Name	Type	Description
`current`	`T`

'bottom'
  | 'bottom left'
  | 'bottom right'
  | 'bottom start'
  | 'bottom end'
  | 'top'
  | 'top left'
  | 'top right'
  | 'top start'
  | 'top end'
  | 'left'
  | 'left top'
  | 'left bottom'
  | 'start'
  | 'start top'
  | 'start bottom'
  | 'right'
  | 'right top'
  | 'right bottom'
  | 'end'
  | 'end top'
  | 'end bottom'

Name	Type	Description
`trigger`	`string \| null`	The name of the component that triggered the popover, e.g. "DialogTrigger" or "ComboBox".
`placement`	`PlacementAxis`	The placement of the popover relative to the trigger.
`isEntering`	`boolean`	Whether the popover is currently entering. Use this to apply animations.
`isExiting`	`boolean`	Whether the popover is currently exiting. Use this to apply animations.

Axis | 'center'

'top'
  | 'bottom'
  | 'left'
  | 'right'

'toggle' | 'replace'

DragHooks & DropHooks

Name	Type	Description
`useDraggableCollectionState`	`( (props: DraggableCollectionStateOpts )) => DraggableCollectionState`
`useDraggableCollection`	`( props: DraggableCollectionOptions, state: DraggableCollectionState, ref: RefObject<HTMLElement \| \| null> ) => void`
`useDraggableItem`	`( (props: DraggableItemProps, , state: DraggableCollectionState )) => DraggableItemResult`
`DragPreview`	`any`
`renderDragPreview`	`( (items: DragItem[] )) => JSX.Element`
`isVirtualDragging`	`() => boolean`

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`isDisabled`	`boolean`	Whether the drag events should be disabled.
`onDragStart`	`( (e: DraggableCollectionStartEvent )) => void`	Handler that is called when a drag operation is started.
`onDragMove`	`( (e: DraggableCollectionMoveEvent )) => void`	Handler that is called when the drag is moved.
`onDragEnd`	`( (e: DraggableCollectionEndEvent )) => void`	Handler that is called when the drag operation is ended, either as a result of a drop or a cancellation.
`preview`	`RefObject<DragPreviewRenderer \| null>`	The ref of the element that will be rendered as the drag preview while dragging.
`getAllowedDropOperations`	`() => DropOperation[]`	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`	The first selected key in the collection.
`lastSelectedKey`	`Key \| null`	The last selected key in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.

Methods

Method	Description
`isSelected( (key: Key )): boolean`	Returns whether a key is selected.
`isSelectionEqual( (selection: Set<Key> )): boolean`	Returns whether the current selection is equal to the given selection.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`	Toggles, replaces, or extends selection to the given key depending on the pointer event and collection's selection mode.
`canSelectItem( (key: Key )): boolean`	Returns whether the given key can be selected.
`isDisabled( (key: Key )): boolean`	Returns whether the given key is non-interactive, i.e. both selection and actions are disabled.
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`isLink( (key: Key )): boolean`	Returns whether the given key is a hyperlink.
`getItemProps( (key: Key )): any`	Returns the props for the given item.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'selection' | 'all'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

'first' | 'last'

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`type`	`'dragstart'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`type`	`'dragmove'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`keys`	`Set<Key>`	The keys of the items that were dragged.
`isInternal`	`boolean`	Whether the drop ended within the same collection as it originated.
`type`	`'dragend'`	The event type.
`dropOperation`	`DropOperation`	The drop operation that occurred.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

'copy'
  | 'link'
  | 'move'
  | 'cancel'

(
  (items: DragItem[],
  , callback: (
    (node: HTMLElement
  )) => void
)) => void

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`draggedKey`	`Key \| null`	The key of the item that initiated a drag.
`draggingKeys`	`Set<Key>`	The keys of the items that are currently being dragged.
`isDisabled`	`boolean`	Whether drag events are disabled.
`preview`	`RefObject<DragPreviewRenderer \| null>`	The ref of the element that will be rendered as the drag preview while dragging.
`getAllowedDropOperations`	`() => DropOperation[]`	Function that returns the drop operations that are allowed for the dragged items. If not provided, all drop operations are allowed.

Methods

Method	Description
`isDragging( (key: Key )): boolean`	Returns whether the given key is currently being dragged.
`getKeysForDrag( (key: Key )): Set<Key>`	Returns the keys of the items that will be dragged with the given key (e.g. selected items).
`getItems( (key: Key )): DragItem[]`	Returns the items to drag for the given key.
`startDrag( (key: Key, , event: DragStartEvent )): void`	Begins a drag for the given key. This triggers the onDragStart event.
`moveDrag( (event: DragMoveEvent )): void`	Triggers an onDragMove event.
`endDrag( (event: DraggableCollectionEndEvent )): void`	Ends the current drag, and emits an onDragEnd event.

Name	Type	Description
`key`	`Key`	The key of the draggable item within the collection.
`hasDragButton`	`boolean`	Whether the item has an explicit focusable drag affordance to initiate accessible drag and drop mode. If true, the dragProps will omit these event handlers, and they will be applied to dragButtonProps instead.
`hasAction`	`boolean`	Whether the item has a primary action (e.g. Enter key or long press) that would conflict with initiating accessible drag and drop. If true, the Alt key must be held to start dragging with a keyboard, and long press is disabled until selection mode is entered. This should be passed from the associated collection item hook (e.g. useOption, useGridListItem, etc.).

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the button is disabled.
`children`	`ReactNode`	—	The content to display in the button.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`rel`	`string`	—	The relationship between the linked resource and the current page. See MDN.
`elementType`	`ElementType \| JSXElementConstructor<any>`	`'button'`	The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Description
`ListDropTargetDelegate`	`any`
`useDroppableCollectionState`	`( (props: DroppableCollectionStateOptions )) => DroppableCollectionState`
`useDroppableCollection`	`( props: DroppableCollectionOptions, state: DroppableCollectionState, ref: RefObject<HTMLElement \| \| null> ) => DroppableCollectionResult`
`useDroppableItem`	`( options: DroppableItemOptions, state: DroppableCollectionState, ref: RefObject<HTMLElement \| \| null> ) => DroppableItemResult`
`useDropIndicator`	`( props: DropIndicatorProps, state: DroppableCollectionState, ref: RefObject<HTMLElement \| \| null> ) => DropIndicatorAria`
`renderDropIndicator`	`( (target: DropTarget )) => JSX.Element`
`dropTargetDelegate`	`DropTargetDelegate`

Name	Type	Default	Description
`collection`	`Collection<Node<unknown>>`	—	A collection of items.
`selectionManager`	`MultipleSelectionManager`	—	An interface for reading and updating multiple selection state.
`isDisabled`	`boolean`	—	Whether the drop events should be disabled.
`acceptedDragTypes`	`'all' \| Array<string \| symbol>`	`'all'`	The drag types that the droppable collection accepts. If the collection accepts directories, include `DIRECTORY_DRAG_TYPE` in your array of allowed types.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler that is called when external items are dropped "between" items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler that is called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler that is called when items are dropped "on" an item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler that is called when items are reordered via drag in the source collection.
`shouldAcceptItemDrop`	`( (target: ItemDropTarget, , types: DragTypes )) => boolean`	—	A function returning whether a given target in the droppable collection is a valid "on" drop target for the current drag types.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters a drop target.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits a drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on a drop target. When defined, this overrides other drop handlers such as `onInsert`, and `onItemDrop`.
`getDropOperation`	`( target: DropTarget, types: DragTypes, allowedOperations: DropOperation[] ) => DropOperation`	—	A function returning the drop operation to be performed when items matching the given types are dropped on the drop target.

TextDropItem
  | FileDropItem
  | DirectoryDropItem

Properties

Name	Type	Description
`kind`	`'text'`	The item kind.
`types`	`Set<string>`	The drag types available for this item. These are often mime types, but may be custom app-specific types.

Methods

Method	Description
`getText( (type: string )): Promise<string>`	Returns the data for the given type as a string.

Properties

Name	Type	Description
`kind`	`'file'`	The item kind.
`type`	`string`	The file type (usually a mime type).
`name`	`string`	The file name.

Methods

Method	Description
`getFile(): Promise<File>`	Returns the contents of the file as a blob.
`getText(): Promise<string>`	Returns the contents of the file as a string.

Properties

Name	Type	Description
`kind`	`'directory'`	The item kind.
`name`	`string`	The directory name.

Methods

Method	Description
`getEntries(): AsyncIterable<FileDropItem \| DirectoryDropItem>`	Returns the entries contained within the directory.

'on'
  | 'before'
  | 'after'

Name	Type	Description
`items`	`DropItem[]`	The dropped items.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`isInternal`	`boolean`	Whether the drag originated within the same collection as the drop.
`target`	`ItemDropTarget`	The drop target.

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'dropenter'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

RootDropTarget | ItemDropTarget

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'dropexit'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'drop'`	The event type.
`dropOperation`	`DropOperation`	The drop operation that should occur.
`items`	`DropItem[]`	The dropped items.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	A collection of items.
`selectionManager`	`MultipleSelectionManager`	An interface for reading and updating multiple selection state.
`target`	`DropTarget \| null`	The current drop target.
`isDisabled`	`boolean`	Whether drop events are disabled.

Methods

Method	Description
`setTarget( (target: DropTarget )): void`	Sets the current drop target.
`isDropTarget( (target: DropTarget )): boolean`	Returns whether the given target is equivalent to the current drop target.
`getDropOperation( (e: DropOperationEvent )): DropOperation`	Returns the drop operation for the given parameters.

Name	Type	Default	Description
`keyboardDelegate`	`KeyboardDelegate`	—	A delegate object that implements behavior for keyboard focus movement.
`dropTargetDelegate`	`DropTargetDelegate`	—	A delegate object that provides drop targets for pointer coordinates within the collection.
`acceptedDragTypes`	`'all' \| Array<string \| symbol>`	`'all'`	The drag types that the droppable collection accepts. If the collection accepts directories, include `DIRECTORY_DRAG_TYPE` in your array of allowed types.
`onInsert`	`( (e: DroppableCollectionInsertDropEvent )) => void`	—	Handler that is called when external items are dropped "between" items.
`onRootDrop`	`( (e: DroppableCollectionRootDropEvent )) => void`	—	Handler that is called when external items are dropped on the droppable collection's root.
`onItemDrop`	`( (e: DroppableCollectionOnItemDropEvent )) => void`	—	Handler that is called when items are dropped "on" an item.
`onReorder`	`( (e: DroppableCollectionReorderEvent )) => void`	—	Handler that is called when items are reordered via drag in the source collection.
`shouldAcceptItemDrop`	`( (target: ItemDropTarget, , types: DragTypes )) => boolean`	—	A function returning whether a given target in the droppable collection is a valid "on" drop target for the current drag types.
`onDropEnter`	`( (e: DroppableCollectionEnterEvent )) => void`	—	Handler that is called when a valid drag enters a drop target.
`onDropExit`	`( (e: DroppableCollectionExitEvent )) => void`	—	Handler that is called when a valid drag exits a drop target.
`onDrop`	`( (e: DroppableCollectionDropEvent )) => void`	—	Handler that is called when a valid drag is dropped on a drop target. When defined, this overrides other drop handlers such as `onInsert`, and `onItemDrop`.
`getDropOperation`	`( target: DropTarget, types: DragTypes, allowedOperations: DropOperation[] ) => DropOperation`	—	A function returning the drop operation to be performed when items matching the given types are dropped on the drop target.

Method	Description
`getKeyBelow( (key: Key )): Key \| null`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key \| null`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key \| null`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key \| null`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key \| null`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key \| null`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key )): Key \| null`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

Method	Description
`getDropTargetFromPoint( x: number, y: number, isValidDropTarget: ( (target: DropTarget )) => boolean ): DropTarget \| null`	Returns a drop target within a collection for the given x and y coordinates. The point is provided relative to the top left corner of the collection container. A drop target can be checked to see if it is valid using the provided `isValidDropTarget` function.

Name	Type	Description
`target`	`DropTarget`	The drop target.
`type`	`'dropactivate'`	The event type.
`x`	`number`	The x coordinate of the event, relative to the target element.
`y`	`number`	The y coordinate of the event, relative to the target element.

Name	Type	Description
`dropIndicatorProps`	`HTMLAttributes<HTMLElement>`	Props for the drop indicator element.
`isDropTarget`	`boolean`	Whether the drop indicator is currently the active drop target.
`isHidden`	`boolean`	Whether the drop indicator is hidden, both visually and from assistive technology. Use this to determine whether to omit the element from the DOM entirely.

Name	Type	Description
`isEmpty`	`boolean`	Whether the listbox has no items and should display its empty state.
`isFocused`	`boolean`	Whether the listbox is currently focused.
`isFocusVisible`	`boolean`	Whether the listbox is currently keyboard focused.
`isDropTarget`	`boolean`	Whether the listbox is currently the active drop target.
`layout`	`'stack' \| 'grid'`	Whether the items are arranged in a stack or grid.
`state`	`ListState<unknown>`	State of the listbox.

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , childFocusStrategy?: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`
`getItemProps( (key: Key )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'all' | Set<Key>

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

'horizontal' | 'vertical'

Name	Type	Description
`isHovered`	`boolean`	Whether the item is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the item is currently in a pressed state.
`isSelected`	`boolean`	Whether the item is currently selected.
`isFocused`	`boolean`	Whether the item is currently focused.
`isFocusVisible`	`boolean`	Whether the item is currently keyboard focused.
`isDisabled`	`boolean`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`allowsDragging`	`boolean`	Whether the item allows dragging.
`isDragging`	`boolean`	Whether the item is currently being dragged.
`isDropTarget`	`boolean`	Whether the item is currently an active drop target.

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

Name	Type	Default	Description
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any. See MDN.
`name`	`string`	—	The name of the input, used when submitting an HTML form.
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Method that is called when the open state of the menu changes.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validate`	`( (value: Key )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`selectedKey`	`Key \| null`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`onSelectionChange`	`( (key: Key )) => void`	—	Handler that is called when the selection changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`children`	`ReactNode \| ( (values: SelectRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: SelectRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: SelectRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Name	Type	Default	Description
`form`	`string`	—	The `<form>` element to associate the button with. The value of this attribute must be the id of a `<form>` in the same document.
`formAction`	`string`	—	The URL that processes the information submitted by the button. Overrides the action attribute of the button's form owner.
`formEncType`	`string`	—	Indicates how to encode the form data that is submitted.
`formMethod`	`string`	—	Indicates the HTTP method used to submit the form.
`formNoValidate`	`boolean`	—	Indicates that the form is not to be validated when it is submitted.
`formTarget`	`string`	—	Overrides the target attribute of the button's form owner.
`name`	`string`	—	Submitted as a pair with the button's value as part of the form data.
`value`	`string`	—	The value associated with the button's name when it's submitted with the form data.
`isPending`	`boolean`	—	Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
`isDisabled`	`boolean`	—	Whether the button is disabled.
`onPress`	`( (e: PressEvent )) => void`	—	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	—	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	—	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	—	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`aria-expanded`	`boolean \| 'true' \| 'false'`	—	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
`aria-haspopup`	`boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-pressed`	`boolean \| 'true' \| 'false' \| 'mixed'`	—	Indicates the current "pressed" state of toggle buttons.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	The behavior of the button when used in an HTML form.
`preventFocusOnPress`	`boolean`	—	Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`onHoverStart`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	—	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	—	Handler that is called when the hover state changes.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`children`	`ReactNode \| ( (values: ButtonRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ButtonRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ButtonRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Name	Type	Default	Description
`trigger`	`string`	—	The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.
`triggerRef`	`RefObject<Element \| null>`	—	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
`isEntering`	`boolean`	—	Whether the popover is currently performing an entry animation.
`isExiting`	`boolean`	—	Whether the popover is currently performing an exit animation.
`UNSTABLE_portalContainer`	`Element`	`document.body`	The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to.
`offset`	`number`	`8`	The additional offset applied along the main axis between the element and its anchor element.
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
`isNonModal`	`boolean`	—	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
`shouldCloseOnInteractOutside`	`( (element: Element )) => boolean`	—	When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
`boundaryElement`	`Element`	`document.body`	Element that that serves as the positioning boundary.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	A ref for the scrollable region within the overlay.
`shouldUpdatePosition`	`boolean`	`true`	Whether the overlay should update its position automatically.
`maxHeight`	`number`	—	The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
`arrowBoundaryOffset`	`number`	`0`	The minimum distance the arrow's edge should be from the edge of the overlay element.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.
`children`	`ReactNode \| ( (values: PopoverRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	—	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: PopoverRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: PopoverRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Name	Type	Default	Description
`selectionBehavior`	`SelectionBehavior`	—	How multiple selection should behave in the collection.
`dragAndDropHooks`	`DragAndDropHooks`	—	The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListBox.
`renderEmptyState`	`( (props: ListBoxRenderProps )) => ReactNode`	—	Provides content to display when there are no items in the list.
`layout`	`'stack' \| 'grid'`	`'stack'`	Whether the items are arranged in a stack or grid.
`orientation`	`Orientation`	`'vertical'`	The primary orientation of the items. Usually this is the direction that the collection scrolls.
`onAction`	`( (key: Key )) => void`	—	Handler that is called when a user performs an action on an item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality.
`autoFocus`	`boolean \| FocusStrategy`	—	Whether to auto focus the listbox or an option.
`shouldFocusWrap`	`boolean`	—	Whether focus should wrap around when the end/start is reached.
`items`	`Iterable<T>`	—	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`selectionMode`	`SelectionMode`	—	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	—	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	—	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => void`	—	Handler that is called when the selection changes.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`children`	`ReactNode \| ( (item: object )) => ReactNode`	—	The contents of the collection.
`dependencies`	`any[]`	—	Values that should invalidate the item cache when using dynamic collections.
`className`	`string \| ( (values: ListBoxRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ListBoxRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`onScroll`	`( (e: UIEvent<Element> )) => void`	—	Handler that is called when a user scrolls. See MDN.

useContextProps<T, U extends SlotProps, E extends Element>(
  props: T
    &  & SlotProps,
  ref: ForwardedRef<E>,
  context: Context<ContextValue<U, E>>
): [
  T,
  RefObject<E
    | null>
]

Name	Type	Description
`slot`	`string \| null`	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

SlottedContextValue<WithRef<T, E>>

SlottedValue<T>
  | T
  | null
  | undefined

T & {ref?: ForwardedRef<E>
}

Properties

Name	Type	Description
`isFocused`	`boolean`	Whether the select is currently focused.
`focusStrategy`	`FocusStrategy \| null`	Controls which item will be auto focused when the menu opens.
`selectedKey`	`Key \| null`	The key for the currently selected item.
`selectedItem`	`Node<T> \| null`	The value of the currently selected item.
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.
`isOpen`	`boolean`	Whether the overlay is currently open.
`realtimeValidation`	`ValidationResult`	Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`	Currently displayed validation results, updated when the user commits their changes.

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the select is focused.
`open( (focusStrategy?: FocusStrategy \| \| null )): void`	Opens the menu.
`toggle( (focusStrategy?: FocusStrategy \| \| null )): void`	Toggles the menu.
`setSelectedKey( (key: Key \| \| null )): void`	Sets the selected key.
`setOpen( (isOpen: boolean )): void`	Sets whether the overlay is open.
`close(): void`	Closes the overlay.
`updateValidation( (result: ValidationResult )): void`	Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`	Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`	Commits the realtime validation so it is displayed to the user.

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

Method	Description
`has( (type: string \| \| symbol )): boolean`	Returns whether the drag contains data of the given type.

Select

Example#

Features#

Anatomy#

Concepts#

Composed components#

Examples#

Starter kits#

Reusable wrappers#

Content#

Selection#

HTML forms#

Links#

Client side routing#

Sections#

Static items#

Dynamic items#

Text slots#

Asynchronous loading#

Disabled#

Disabled options#

Validation#

Description#

Controlled open state#

Customizing SelectValue#

Props#

Select#

Label#

Button#

SelectValue#

Popover#

ListBox#

Section#

Header#

ListBoxItem#

FieldError#

Styling#

Select#

Label#

Button#

SelectValue#

Popover#

ListBox#

Section#

Header#

ListBoxItem#

Text#

FieldError#

Advanced customization#

Composition#

Contexts#

Custom children#

State#

Hooks#

Accessibility#

False positives#

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods

Properties

Methods