ListBox

A listbox displays a list of options and allows a user to select one or more of them.

Example#

import {ListBox, Item} from 'react-aria-components';

<ListBox aria-label="Favorite animal" selectionMode="single">
  <Item>Aardvark</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Kangaroo</Item>
  <Item>Panda</Item>
  <Item>Snake</Item>
</ListBox>

import {Item, ListBox} from 'react-aria-components';

<ListBox
  aria-label="Favorite animal"
  selectionMode="single"
>
  <Item>Aardvark</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Kangaroo</Item>
  <Item>Panda</Item>
  <Item>Snake</Item>
</ListBox>

import {
  Item,
  ListBox
} from 'react-aria-components';

<ListBox
  aria-label="Favorite animal"
  selectionMode="single"
>
  <Item>Aardvark</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Kangaroo</Item>
  <Item>Panda</Item>
  <Item>Snake</Item>
</ListBox>

.react-aria-ListBox {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }

  .react-aria-Item {
    margin: 2px;
    padding: 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[aria-selected=true] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }
    }

    &[aria-disabled] {
      color: var(--text-color-disabled);
    }

    [slot=label] {
      font-weight: bold;
    }

    [slot=description] {
      font-size: small;
    }
  }
}

@media (forced-colors: active) {
  .react-aria-ListBox {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --separator-color: ButtonBorder;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }
}

.react-aria-ListBox {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }

  .react-aria-Item {
    margin: 2px;
    padding: 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[aria-selected=true] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }
    }

    &[aria-disabled] {
      color: var(--text-color-disabled);
    }

    [slot=label] {
      font-weight: bold;
    }

    [slot=description] {
      font-size: small;
    }
  }
}

@media (forced-colors: active) {
  .react-aria-ListBox {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --separator-color: ButtonBorder;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }
}

.react-aria-ListBox {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

  .react-aria-Header {
    font-size: 1.143rem;
    font-weight: bold;
    padding: 0 0.714rem;
  }

  .react-aria-Item {
    margin: 2px;
    padding: 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[aria-selected=true] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }
    }

    &[aria-disabled] {
      color: var(--text-color-disabled);
    }

    [slot=label] {
      font-weight: bold;
    }

    [slot=description] {
      font-size: small;
    }
  }
}

@media (forced-colors: active) {
  .react-aria-ListBox {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --separator-color: ButtonBorder;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }
}

Features#

A listbox can be built using the <select> and <option> HTML elements, but this is not possible to style consistently cross browser. ListBox helps you build accessible listbox components that can be styled as needed.

• Item selection – Single or multiple selection, disabled rows, and both toggle and replace selection behaviors.
• Keyboard navigation – List items can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
• Touch friendly – Selection behavior adapts depending on the device. For example, selection occurs on mouse down but on touch up, which is consistent with native conventions.
• 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.
• Styleable – Items include builtin states for styling, such as hover, press, focus, selected, and disabled.

Note: ListBox only handles the list itself. For a dropdown, see Select.

Anatomy#

A listbox consists of a container element, with a list of options or groups inside. Users can select one or more options by clicking, tapping, or navigating with the keyboard.

Concepts#

ListBox makes use of the following concepts:

• Collections
• Selection

Props#

ListBox#

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.

Header#

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

Item#

An <Item> 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 typeahead in the ListBox.

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-ListBox {
  /* ... */
}

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

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

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

<ListBox className="my-listbox">
  {/* ... */}
</ListBox>

<ListBox className="my-listbox">
  {/* ... */}
</ListBox>

<ListBox className="my-listbox">
  {/* ... */}
</ListBox>

In addition, some components support multiple UI states (e.g. pressed, hovered, etc.). React Aria components expose states using DOM attributes, which you can target in CSS selectors. These are ARIA attributes wherever possible, or data attributes when a relevant ARIA attribute does not exist. For example:

.react-aria-Item[aria-selected=true] {
  /* ... */
}

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

.react-aria-Item[aria-selected=true] {
  /* ... */
}

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

.react-aria-Item[aria-selected=true] {
  /* ... */
}

.react-aria-Item[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.

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

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

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

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.

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

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

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

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

ListBox#

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

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.

Item#

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

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.

Reusable wrappers#

If you will use a ListBox 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 ListBox 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. The Item component is also wrapped to apply class names based on the current state, as described above.

import type {ItemProps, ListBoxProps} from 'react-aria-components';

function MyListBox<T extends object>({ children, ...props }: ListBoxProps<T>) {
  return (
    <ListBox {...props} className="my-listbox">
      {children}
    </ListBox>
  );
}

function MyItem(props: ItemProps) {
  return (
    <Item
      {...props}
      className={({ isFocusVisible, isSelected }) =>
        `my-item ${isFocusVisible ? 'focused' : ''} ${
          isSelected ? 'selected' : ''
        }`}
    />
  );
}

<MyListBox aria-label="Ice cream flavor" selectionMode="single">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyListBox>

import type {
  ItemProps,
  ListBoxProps
} from 'react-aria-components';

function MyListBox<T extends object>(
  { children, ...props }: ListBoxProps<T>
) {
  return (
    <ListBox {...props} className="my-listbox">
      {children}
    </ListBox>
  );
}

function MyItem(props: ItemProps) {
  return (
    <Item
      {...props}
      className={({ isFocusVisible, isSelected }) =>
        `my-item ${isFocusVisible ? 'focused' : ''} ${
          isSelected ? 'selected' : ''
        }`}
    />
  );
}

<MyListBox
  aria-label="Ice cream flavor"
  selectionMode="single"
>
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyListBox>

import type {
  ItemProps,
  ListBoxProps
} from 'react-aria-components';

function MyListBox<
  T extends object
>(
  { children, ...props }:
    ListBoxProps<T>
) {
  return (
    <ListBox
      {...props}
      className="my-listbox"
    >
      {children}
    </ListBox>
  );
}

function MyItem(
  props: ItemProps
) {
  return (
    <Item
      {...props}
      className={(
        {
          isFocusVisible,
          isSelected
        }
      ) =>
        `my-item ${
          isFocusVisible
            ? 'focused'
            : ''
        } ${
          isSelected
            ? 'selected'
            : ''
        }`}
    />
  );
}

<MyListBox
  aria-label="Ice cream flavor"
  selectionMode="single"
>
  <MyItem>
    Chocolate
  </MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>
    Strawberry
  </MyItem>
  <MyItem>
    Vanilla
  </MyItem>
</MyListBox>

.my-listbox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  border-radius: 6px;
  background: var(--page-background);
  outline: none;
  max-width: 250px;
  max-height: 300px;
  box-sizing: border-box;
}

.my-item {
  --highlight: #e70073;

  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;

  &.selected {
    background: var(--highlight);
    color: white;
  }

  &.focused {
    box-shadow: 0 0 0 2px var(--page-background), 0 0 0 4px var(--highlight);
  }
}

@media (forced-colors: active) {
  .my-listbox {
    forced-color-adjust: none;
    border-color: ButtonBorder;
    background: Canvas;
  }

  .my-item {
    color: ButtonText;
    --highlight: Highlight;

    &.selected {
      color: HighlightText;
    }
  }
}

.my-listbox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  border-radius: 6px;
  background: var(--page-background);
  outline: none;
  max-width: 250px;
  max-height: 300px;
  box-sizing: border-box;
}

.my-item {
  --highlight: #e70073;

  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;

  &.selected {
    background: var(--highlight);
    color: white;
  }

  &.focused {
    box-shadow: 0 0 0 2px var(--page-background), 0 0 0 4px var(--highlight);
  }
}

@media (forced-colors: active) {
  .my-listbox {
    forced-color-adjust: none;
    border-color: ButtonBorder;
    background: Canvas;
  }

  .my-item {
    color: ButtonText;
    --highlight: Highlight;

    &.selected {
      color: HighlightText;
    }
  }
}

.my-listbox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  border-radius: 6px;
  background: var(--page-background);
  outline: none;
  max-width: 250px;
  max-height: 300px;
  box-sizing: border-box;
}

.my-item {
  --highlight: #e70073;

  margin: 2px;
  padding: 0.286rem 0.571rem;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;

  &.selected {
    background: var(--highlight);
    color: white;
  }

  &.focused {
    box-shadow: 0 0 0 2px var(--page-background), 0 0 0 4px var(--highlight);
  }
}

@media (forced-colors: active) {
  .my-listbox {
    forced-color-adjust: none;
    border-color: ButtonBorder;
    background: Canvas;
  }

  .my-item {
    color: ButtonText;
    --highlight: Highlight;

    &.selected {
      color: HighlightText;
    }
  }
}

Usage#

Dynamic collections#

ListBox 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 ListBox 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: 'Aardvark' },
    { id: 2, name: 'Cat' },
    { id: 3, name: 'Dog' },
    { id: 4, name: 'Kangaroo' },
    { id: 5, name: 'Koala' },
    { id: 6, name: 'Penguin' },
    { id: 7, name: 'Snake' },
    { id: 8, name: 'Turtle' },
    { id: 9, name: 'Wombat' }
  ];

  return (
    <ListBox aria-label="Animals" items={options} selectionMode="single">
      {(item) => <Item>{item.name}</Item>}
    </ListBox>
  );
}

function Example() {
  let options = [
    { id: 1, name: 'Aardvark' },
    { id: 2, name: 'Cat' },
    { id: 3, name: 'Dog' },
    { id: 4, name: 'Kangaroo' },
    { id: 5, name: 'Koala' },
    { id: 6, name: 'Penguin' },
    { id: 7, name: 'Snake' },
    { id: 8, name: 'Turtle' },
    { id: 9, name: 'Wombat' }
  ];

  return (
    <ListBox
      aria-label="Animals"
      items={options}
      selectionMode="single"
    >
      {(item) => <Item>{item.name}</Item>}
    </ListBox>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name: 'Aardvark'
    },
    {
      id: 2,
      name: 'Cat'
    },
    {
      id: 3,
      name: 'Dog'
    },
    {
      id: 4,
      name: 'Kangaroo'
    },
    {
      id: 5,
      name: 'Koala'
    },
    {
      id: 6,
      name: 'Penguin'
    },
    {
      id: 7,
      name: 'Snake'
    },
    {
      id: 8,
      name: 'Turtle'
    },
    {
      id: 9,
      name: 'Wombat'
    }
  ];

  return (
    <ListBox
      aria-label="Animals"
      items={options}
      selectionMode="single"
    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </ListBox>
  );
}

Selection#

ListBox supports multiple selection modes. By default, selection is disabled, however this can be changed using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected items (uncontrolled) and selectedKeys to set the selected items (controlled). The value of the selected keys must match the id prop of the items. See the react-stately Selection docs for more details.

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

function Example() {
  let [selected, setSelected] = React.useState<Selection>(new Set(['cheese']));

  return (
    <>
      <ListBox
        aria-label="Sandwich contents"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item id="lettuce">Lettuce</Item>
        <Item id="tomato">Tomato</Item>
        <Item id="cheese">Cheese</Item>
        <Item id="tuna">Tuna Salad</Item>
        <Item id="egg">Egg Salad</Item>
        <Item id="ham">Ham</Item>
      </ListBox>
      <p>
        Current selection (controlled):{' '}
        {selected === 'all' ? 'all' : [...selected].join(', ')}
      </p>
    </>
  );
}

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

function Example() {
  let [selected, setSelected] = React.useState<Selection>(
    new Set(['cheese'])
  );

  return (
    <>
      <ListBox
        aria-label="Sandwich contents"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item id="lettuce">Lettuce</Item>
        <Item id="tomato">Tomato</Item>
        <Item id="cheese">Cheese</Item>
        <Item id="tuna">Tuna Salad</Item>
        <Item id="egg">Egg Salad</Item>
        <Item id="ham">Ham</Item>
      </ListBox>
      <p>
        Current selection (controlled): {selected === 'all'
          ? 'all'
          : [...selected].join(', ')}
      </p>
    </>
  );
}

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

function Example() {
  let [
    selected,
    setSelected
  ] = React.useState<
    Selection
  >(new Set(['cheese']));

  return (
    <>
      <ListBox
        aria-label="Sandwich contents"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Item id="lettuce">
          Lettuce
        </Item>
        <Item id="tomato">
          Tomato
        </Item>
        <Item id="cheese">
          Cheese
        </Item>
        <Item id="tuna">
          Tuna Salad
        </Item>
        <Item id="egg">
          Egg Salad
        </Item>
        <Item id="ham">
          Ham
        </Item>
      </ListBox>
      <p>
        Current selection
        (controlled):
        {' '}
        {selected ===
            'all'
          ? 'all'
          : [...selected]
            .join(', ')}
      </p>
    </>
  );
}

Selection behavior#

By default, ListBox uses the "toggle" selection behavior, which behaves like a checkbox group: clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection.

When selectionBehavior is set to "replace", clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.

These selection behaviors are defined in Aria Practices.

<ListBox
  aria-label="Sandwich contents"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <Item id="lettuce">Lettuce</Item>
  <Item id="tomato">Tomato</Item>
  <Item id="cheese">Cheese</Item>
  <Item id="tuna">Tuna Salad</Item>
  <Item id="egg">Egg Salad</Item>
  <Item id="ham">Ham</Item>
</ListBox>

<ListBox
  aria-label="Sandwich contents"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <Item id="lettuce">Lettuce</Item>
  <Item id="tomato">Tomato</Item>
  <Item id="cheese">Cheese</Item>
  <Item id="tuna">Tuna Salad</Item>
  <Item id="egg">Egg Salad</Item>
  <Item id="ham">Ham</Item>
</ListBox>

<ListBox
  aria-label="Sandwich contents"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <Item id="lettuce">
    Lettuce
  </Item>
  <Item id="tomato">
    Tomato
  </Item>
  <Item id="cheese">
    Cheese
  </Item>
  <Item id="tuna">
    Tuna Salad
  </Item>
  <Item id="egg">
    Egg Salad
  </Item>
  <Item id="ham">
    Ham
  </Item>
</ListBox>

Sections#

ListBox 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';

<ListBox aria-label="Sandwich contents" selectionMode="multiple">
  <Section>
    <Header>Veggies</Header>
    <Item id="lettuce">Lettuce</Item>
    <Item id="tomato">Tomato</Item>
    <Item id="onion">Onion</Item>
  </Section>
  <Section>
    <Header>Protein</Header>
    <Item id="ham">Ham</Item>
    <Item id="tuna">Tuna</Item>
    <Item id="tofu">Tofu</Item>
  </Section>
  <Section>
    <Header>Condiments</Header>
    <Item id="mayo">Mayonaise</Item>
    <Item id="mustard">Mustard</Item>
    <Item id="ranch">Ranch</Item>
  </Section>
</ListBox>

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

<ListBox
  aria-label="Sandwich contents"
  selectionMode="multiple"
>
  <Section>
    <Header>Veggies</Header>
    <Item id="lettuce">Lettuce</Item>
    <Item id="tomato">Tomato</Item>
    <Item id="onion">Onion</Item>
  </Section>
  <Section>
    <Header>Protein</Header>
    <Item id="ham">Ham</Item>
    <Item id="tuna">Tuna</Item>
    <Item id="tofu">Tofu</Item>
  </Section>
  <Section>
    <Header>Condiments</Header>
    <Item id="mayo">Mayonaise</Item>
    <Item id="mustard">Mustard</Item>
    <Item id="ranch">Ranch</Item>
  </Section>
</ListBox>

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

<ListBox
  aria-label="Sandwich contents"
  selectionMode="multiple"
>
  <Section>
    <Header>
      Veggies
    </Header>
    <Item id="lettuce">
      Lettuce
    </Item>
    <Item id="tomato">
      Tomato
    </Item>
    <Item id="onion">
      Onion
    </Item>
  </Section>
  <Section>
    <Header>
      Protein
    </Header>
    <Item id="ham">
      Ham
    </Item>
    <Item id="tuna">
      Tuna
    </Item>
    <Item id="tofu">
      Tofu
    </Item>
  </Section>
  <Section>
    <Header>
      Condiments
    </Header>
    <Item id="mayo">
      Mayonaise
    </Item>
    <Item id="mustard">
      Mustard
    </Item>
    <Item id="ranch">
      Ranch
    </Item>
  </Section>
</ListBox>

Dynamic items#

The above example shows sections with static items. Sections can also be populated from a heirarchical data structure. Similarly to the props on ListBox, <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 type {Selection} from 'react-aria-components';
import {Collection} from 'react-aria-components';

function Example() {
  let options = [
    {name: 'Australian', children: [
      {id: 2, name: 'Koala'},
      {id: 3, name: 'Kangaroo'},
      {id: 4, name: 'Platypus'}
    ]},
    {name: 'American', children: [
      {id: 6, name: 'Bald Eagle'},
      {id: 7, name: 'Bison'},
      {id: 8, name: 'Skunk'}
    ]}
  ];
  let [selected, setSelected] = React.useState<Selection>(new Set());

  return (
    <ListBox
      aria-label="Pick an animal"
      items={options}
      selectedKeys={selected}
      selectionMode="single"
      onSelectionChange={setSelected}>
      {section => (
        <Section id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {item => <Item>{item.name}</Item>}
          </Collection>
        </Section>
      )}
    </ListBox>
  );
}

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

function Example() {
  let options = [
    {
      name: 'Australian',
      children: [
        { id: 2, name: 'Koala' },
        { id: 3, name: 'Kangaroo' },
        { id: 4, name: 'Platypus' }
      ]
    },
    {
      name: 'American',
      children: [
        { id: 6, name: 'Bald Eagle' },
        { id: 7, name: 'Bison' },
        { id: 8, name: 'Skunk' }
      ]
    }
  ];
  let [selected, setSelected] = React.useState<Selection>(
    new Set()
  );

  return (
    <ListBox
      aria-label="Pick an animal"
      items={options}
      selectedKeys={selected}
      selectionMode="single"
      onSelectionChange={setSelected}
    >
      {(section) => (
        <Section id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {(item) => <Item>{item.name}</Item>}
          </Collection>
        </Section>
      )}
    </ListBox>
  );
}

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

function Example() {
  let options = [
    {
      name: 'Australian',
      children: [
        {
          id: 2,
          name: 'Koala'
        },
        {
          id: 3,
          name:
            'Kangaroo'
        },
        {
          id: 4,
          name:
            'Platypus'
        }
      ]
    },
    {
      name: 'American',
      children: [
        {
          id: 6,
          name:
            'Bald Eagle'
        },
        {
          id: 7,
          name: 'Bison'
        },
        {
          id: 8,
          name: 'Skunk'
        }
      ]
    }
  ];
  let [
    selected,
    setSelected
  ] = React.useState<
    Selection
  >(new Set());

  return (
    <ListBox
      aria-label="Pick an animal"
      items={options}
      selectedKeys={selected}
      selectionMode="single"
      onSelectionChange={setSelected}
    >
      {(section) => (
        <Section
          id={section
            .name}
        >
          <Header>
            {section
              .name}
          </Header>
          <Collection
            items={section
              .children}
          >
            {(item) => (
              <Item>
                {item
                  .name}
              </Item>
            )}
          </Collection>
        </Section>
      )}
    </ListBox>
  );
}

Accessibility#

Sections without a title must provide an aria-label for accessibility.

Complex options#

By default, options items that only contain text will be labeled by the contents of the item. The <Text> component may be used to add a description using the slot="description" prop. Slots improve screen reader announcements, and may also be used for styling and layout purposes.

NOTE: listbox options cannot contain interactive content (e.g. buttons, checkboxes, etc.). For these cases, see GridList instead.

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

<ListBox aria-label="Permissions" selectionMode="single">
  <Item textValue="Read">
    <Text slot="label">Read</Text>
    <Text slot="description">Read only</Text>
  </Item>
  <Item textValue="Write">
    <Text slot="label">Write</Text>
    <Text slot="description">Read and write only</Text>
  </Item>
  <Item textValue="Admin">
    <Text slot="label">Admin</Text>
    <Text slot="description">Full access</Text>
  </Item>
</ListBox>

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

<ListBox aria-label="Permissions" selectionMode="single">
  <Item textValue="Read">
    <Text slot="label">Read</Text>
    <Text slot="description">Read only</Text>
  </Item>
  <Item textValue="Write">
    <Text slot="label">Write</Text>
    <Text slot="description">Read and write only</Text>
  </Item>
  <Item textValue="Admin">
    <Text slot="label">Admin</Text>
    <Text slot="description">Full access</Text>
  </Item>
</ListBox>

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

<ListBox
  aria-label="Permissions"
  selectionMode="single"
>
  <Item textValue="Read">
    <Text slot="label">
      Read
    </Text>
    <Text slot="description">
      Read only
    </Text>
  </Item>
  <Item textValue="Write">
    <Text slot="label">
      Write
    </Text>
    <Text slot="description">
      Read and write
      only
    </Text>
  </Item>
  <Item textValue="Admin">
    <Text slot="label">
      Admin
    </Text>
    <Text slot="description">
      Full access
    </Text>
  </Item>
</ListBox>

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, or support features like infinite scroll to load more data.

import {useAsyncList} from '@react-stately/data';

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 (
    <ListBox
      aria-label="Pick a Pokemon"
      items={list.items}
      selectionMode="single"
    >
      {(item) => <Item id={item.name}>{item.name}</Item>}
    </ListBox>
  );
}

import {useAsyncList} from '@react-stately/data';

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 (
    <ListBox
      aria-label="Pick a Pokemon"
      items={list.items}
      selectionMode="single"
    >
      {(item) => <Item id={item.name}>{item.name}</Item>}
    </ListBox>
  );
}

import {useAsyncList} from '@react-stately/data';

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 (
    <ListBox
      aria-label="Pick a Pokemon"
      items={list.items}
      selectionMode="single"
    >
      {(item) => (
        <Item
          id={item.name}
        >
          {item.name}
        </Item>
      )}
    </ListBox>
  );
}

Disabled items#

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

<ListBox
  aria-label="Choose sandwich contents"
  selectionMode="multiple"
  disabledKeys={['tuna']}
>
  <Item id="lettuce">Lettuce</Item>
  <Item id="tomato">Tomato</Item>
  <Item id="cheese">Cheese</Item>
  <Item id="tuna">Tuna Salad</Item>
  <Item id="egg">Egg Salad</Item>
  <Item id="ham">Ham</Item>
</ListBox>

<ListBox
  aria-label="Choose sandwich contents"
  selectionMode="multiple"
  disabledKeys={['tuna']}
>
  <Item id="lettuce">Lettuce</Item>
  <Item id="tomato">Tomato</Item>
  <Item id="cheese">Cheese</Item>
  <Item id="tuna">Tuna Salad</Item>
  <Item id="egg">Egg Salad</Item>
  <Item id="ham">Ham</Item>
</ListBox>

<ListBox
  aria-label="Choose sandwich contents"
  selectionMode="multiple"
  disabledKeys={[
    'tuna'
  ]}
>
  <Item id="lettuce">
    Lettuce
  </Item>
  <Item id="tomato">
    Tomato
  </Item>
  <Item id="cheese">
    Cheese
  </Item>
  <Item id="tuna">
    Tuna Salad
  </Item>
  <Item id="egg">
    Egg Salad
  </Item>
  <Item id="ham">
    Ham
  </Item>
</ListBox>

Empty state#

Use the renderEmptyState prop to customize what the ListBox will display if there are no items.

<ListBox
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}
>
  {[]}
</ListBox>

<ListBox
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}
>
  {[]}
</ListBox>

<ListBox
  aria-label="Search results"
  renderEmptyState={() =>
    'No results found.'}
>
  {[]}
</ListBox>

Drag and drop#

ListBox supports drag and drop interactions when the dragAndDropHooks prop is provided using the useDragAndDrop hook. Users can drop data on the list as a whole, on individual items, insert new items between existing ones, or reorder items.

React Aria supports traditional mouse and touch based drag and drop, but also implements keyboard and screen reader friendly interactions. Users can press Enter on a draggable element to enter drag and drop mode. Then, they can press Tab to navigate between drop targets. A droppable collection is treated as a single drop target, so that users can easily tab past it to get to the next drop target. Within a droppable collection, keys such as ArrowDown and ArrowUp can be used to select a drop position, such as on an item, or between items.

See the drag and drop introduction to learn more.

Reorderable#

This example shows a basic list that allows users to reorder items via drag and drop. This is enabled using the onReorder event handler, provided to the useDragAndDrop hook. The getItems function must also be implemented for items to become draggable. See below for more details.

This uses useListData from React Stately to manage the item list. Note that useListData is a convenience hook, not a requirement. You can manage your state however you wish.

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'Adobe Photoshop' },
      { id: 2, name: 'Adobe XD' },
      { id: 3, name: 'Adobe Dreamweaver' },
      { id: 4, name: 'Adobe InDesign' },
      { id: 5, name: 'Adobe Connect' }
    ]
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({ 'text/plain': list.getItem(key).name })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        list.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        list.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <ListBox
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => <Item>{item.name}</Item>}
    </ListBox>
  );
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'Adobe Photoshop' },
      { id: 2, name: 'Adobe XD' },
      { id: 3, name: 'Adobe Dreamweaver' },
      { id: 4, name: 'Adobe InDesign' },
      { id: 5, name: 'Adobe Connect' }
    ]
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': list.getItem(key).name
      })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        list.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        list.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <ListBox
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => <Item>{item.name}</Item>}
    </ListBox>
  );
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData(
    {
      initialItems: [
        {
          id: 1,
          name:
            'Adobe Photoshop'
        },
        {
          id: 2,
          name:
            'Adobe XD'
        },
        {
          id: 3,
          name:
            'Adobe Dreamweaver'
        },
        {
          id: 4,
          name:
            'Adobe InDesign'
        },
        {
          id: 5,
          name:
            'Adobe Connect'
        }
      ]
    }
  );

  let {
    dragAndDropHooks
  } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map(
        (key) => ({
          'text/plain':
            list.getItem(
              key
            ).name
        })
      ),
    onReorder(e) {
      if (
        e.target
          .dropPosition ===
          'before'
      ) {
        list.moveBefore(
          e.target.key,
          e.keys
        );
      } else if (
        e.target
          .dropPosition ===
          'after'
      ) {
        list.moveAfter(
          e.target.key,
          e.keys
        );
      }
    }
  });
  return (
    <ListBox
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </ListBox>
  );
}

.react-aria-Item {
  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[aria-selected=true] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator[data-drop-target] {
  outline: 1px solid var(--highlight-background);
}

.react-aria-Item {
  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[aria-selected=true] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator[data-drop-target] {
  outline: 1px solid var(--highlight-background);
}

.react-aria-Item {
  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[aria-selected=true] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator[data-drop-target] {
  outline: 1px solid var(--highlight-background);
}

Custom drag preview#

By default, the drag preview shown under the user's pointer or finger is a copy of the original element that started the drag. A custom preview can be rendered by implementing the renderDragPreview function, passed to useDragAndDrop. This receives the dragged data that was returned by getItems, and returns a rendered preview for those items.

This example renders a custom drag preview which shows the number of items being dragged.

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {dragAndDropHooks} = useDragAndDrop({
    // ...
    renderDragPreview(items) {
      return (
        <div className="drag-preview">
          {items[0]['text/plain']}
          <span className="badge">{items.length}</span>
        </div>
      );
    }  });

  // ...
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {dragAndDropHooks} = useDragAndDrop({
    // ...
    renderDragPreview(items) {
      return (
        <div className="drag-preview">
          {items[0]['text/plain']}
          <span className="badge">{items.length}</span>
        </div>
      );
    }  });

  // ...
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {
    dragAndDropHooks
  } = useDragAndDrop({
    // ...
    renderDragPreview(
      items
    ) {
      return (
        <div className="drag-preview">
          {items[0][
            'text/plain'
          ]}
          <span className="badge">
            {items
              .length}
          </span>
        </div>
      );
    }  });

  // ...
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

Drag data#

Data for draggable items can be provided in multiple formats at once. This allows drop targets to choose data in a format that they understand. For example, you could serialize a complex object as JSON in a custom format for use within your own application, and also provide plain text and/or rich HTML fallbacks that can be used when a user drops data in an external application (e.g. an email message).

This can be done by returning multiple keys for an item from the getItems function. Types can either be a standard mime type for interoperability with external applications, or a custom string for use within your own app.

This example provides representations of each item as plain text, HTML, and a custom app-specific data format. Dropping on the drop targets in this page will use the custom data format to render formatted items. If you drop in an external application supporting rich text, the HTML representation will be used. Dropping in a text editor will use the plain text format.

function DraggableListBox() {
  let items = new Map([
    ['ps', { name: 'Photoshop', style: 'strong' }],
    ['xd', { name: 'XD', style: 'strong' }],
    ['id', { name: 'InDesign', style: 'strong' }],
    ['dw', { name: 'Dreamweaver', style: 'em' }],
    ['co', { name: 'Connect', style: 'em' }]
  ]);

  let { dragAndDropHooks } = useDragAndDrop({
    getItems(keys) {
      return [...keys].map((key) => {
        let item = items.get(key as string)!;
        return {
          'text/plain': item.name,
          'text/html': `<${item.style}>${item.name}</${item.style}>`,
          'custom-app-type': JSON.stringify({ id: key, ...item })
        };
      });
    }  });

  return (
    <ListBox
      aria-label="Draggable list"
      selectionMode="multiple"
      items={items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {([id, item]) => (
        <Item id={id} textValue={item.name}>
          {React.createElement(item.style || 'span', null, item.name)}
        </Item>
      )}
    </ListBox>
  );
}

<div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
  <DraggableListBox />
  {/* see below */}
  <DroppableListBox />
</div>

function DraggableListBox() {
  let items = new Map([
    ['ps', { name: 'Photoshop', style: 'strong' }],
    ['xd', { name: 'XD', style: 'strong' }],
    ['id', { name: 'InDesign', style: 'strong' }],
    ['dw', { name: 'Dreamweaver', style: 'em' }],
    ['co', { name: 'Connect', style: 'em' }]
  ]);

  let { dragAndDropHooks } = useDragAndDrop({
    getItems(keys) {
      return [...keys].map((key) => {
        let item = items.get(key as string)!;
        return {
          'text/plain': item.name,
          'text/html':
            `<${item.style}>${item.name}</${item.style}>`,
          'custom-app-type': JSON.stringify({
            id: key,
            ...item
          })
        };
      });
    }  });

  return (
    <ListBox
      aria-label="Draggable list"
      selectionMode="multiple"
      items={items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {([id, item]) => (
        <Item id={id} textValue={item.name}>
          {React.createElement(
            item.style || 'span',
            null,
            item.name
          )}
        </Item>
      )}
    </ListBox>
  );
}

<div
  style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}
>
  <DraggableListBox />
  {/* see below */}
  <DroppableListBox />
</div>