ListBox

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

Example#

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

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

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

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

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

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

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

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

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

.react-aria-ListBoxItem {
  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] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -2px;
  }

  &[data-selected] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);

    &[data-focus-visible] {
      outline-color: var(--highlight-foreground);
      outline-offset: -4px;
    }
  }
}

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

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

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

.react-aria-ListBoxItem {
  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] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -2px;
  }

  &[data-selected] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);

    &[data-focus-visible] {
      outline-color: var(--highlight-foreground);
      outline-offset: -4px;
    }
  }
}

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

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

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

.react-aria-ListBoxItem {
  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] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: -2px;
  }

  &[data-selected] {
    background: var(--highlight-background);
    color: var(--highlight-foreground);

    &[data-focus-visible] {
      outline-color: var(--highlight-foreground);
      outline-offset: -4px;
    }
  }
}

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.
• Layout options – Items can be arranged in a vertical or horizontal stack, or as a two-dimensional grid.
• Drag and drop – ListBox supports drag and drop to reorder, insert, or update items via mouse, touch, keyboard, and screen reader interactions.
• 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 items or sections inside. Users can select one or more items by clicking, tapping, or navigating with the keyboard.

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

<ListBox>
  <ListBoxItem>
    <Text slot="label" />
    <Text slot="description" />
  </ListBoxItem>
  <Section>
    <Header />
    <ListBoxItem />
  </Section>
</ListBox>

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

<ListBox>
  <ListBoxItem>
    <Text slot="label" />
    <Text slot="description" />
  </ListBoxItem>
  <Section>
    <Header />
    <ListBoxItem />
  </Section>
</ListBox>

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

<ListBox>
  <ListBoxItem>
    <Text slot="label" />
    <Text slot="description" />
  </ListBoxItem>
  <Section>
    <Header />
    <ListBoxItem />
  </Section>
</ListBox>

Concepts#

ListBox makes use of the following concepts:

Examples#

Contact List

A ListBox featuring sticky section headers and multiple selection.

Image Grid

An async image gallery with selectable items, 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 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 ListBoxItem component is also wrapped to apply class names based on the current state, as described in the styling section.

import type {ListBoxItemProps, 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: ListBoxItemProps) {
  return (
    <ListBoxItem
      {...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 {
  ListBoxItemProps,
  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: ListBoxItemProps) {
  return (
    <ListBoxItem
      {...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 {
  ListBoxItemProps,
  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: ListBoxItemProps
) {
  return (
    <ListBoxItem
      {...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(--border-color);
  border-radius: 6px;
  background: var(--overlay-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(--text-color);
  font-size: 1.072rem;

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

  &.focused {
    outline: 2px solid var(--highlight);
    outline-offset: 2px;
  }
}

@media (forced-colors: active) {
  .my-item {
    forced-color-adjust: none;
    --highlight: Highlight;
  }
}

.my-listbox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--overlay-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(--text-color);
  font-size: 1.072rem;

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

  &.focused {
    outline: 2px solid var(--highlight);
    outline-offset: 2px;
  }
}

@media (forced-colors: active) {
  .my-item {
    forced-color-adjust: none;
    --highlight: Highlight;
  }
}

.my-listbox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--overlay-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(--text-color);
  font-size: 1.072rem;

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

  &.focused {
    outline: 2px solid var(--highlight);
    outline-offset: 2px;
  }
}

@media (forced-colors: active) {
  .my-item {
    forced-color-adjust: none;
    --highlight: Highlight;
  }
}

Content#

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) => <ListBoxItem>{item.name}</ListBoxItem>}
    </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) => <ListBoxItem>{item.name}</ListBoxItem>}
    </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) => (
        <ListBoxItem>
          {item.name}
        </ListBoxItem>
      )}
    </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 Selection guide 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}      >
        <ListBoxItem id="lettuce">Lettuce</ListBoxItem>
        <ListBoxItem id="tomato">Tomato</ListBoxItem>
        <ListBoxItem id="cheese">Cheese</ListBoxItem>
        <ListBoxItem id="tuna">Tuna Salad</ListBoxItem>
        <ListBoxItem id="egg">Egg Salad</ListBoxItem>
        <ListBoxItem id="ham">Ham</ListBoxItem>
      </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}      >
        <ListBoxItem id="lettuce">Lettuce</ListBoxItem>
        <ListBoxItem id="tomato">Tomato</ListBoxItem>
        <ListBoxItem id="cheese">Cheese</ListBoxItem>
        <ListBoxItem id="tuna">Tuna Salad</ListBoxItem>
        <ListBoxItem id="egg">Egg Salad</ListBoxItem>
        <ListBoxItem id="ham">Ham</ListBoxItem>
      </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}      >
        <ListBoxItem id="lettuce">
          Lettuce
        </ListBoxItem>
        <ListBoxItem id="tomato">
          Tomato
        </ListBoxItem>
        <ListBoxItem id="cheese">
          Cheese
        </ListBoxItem>
        <ListBoxItem id="tuna">
          Tuna Salad
        </ListBoxItem>
        <ListBoxItem id="egg">
          Egg Salad
        </ListBoxItem>
        <ListBoxItem id="ham">
          Ham
        </ListBoxItem>
      </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">
  <ListBoxItem id="lettuce">Lettuce</ListBoxItem>
  <ListBoxItem id="tomato">Tomato</ListBoxItem>
  <ListBoxItem id="cheese">Cheese</ListBoxItem>
  <ListBoxItem id="tuna">Tuna Salad</ListBoxItem>
  <ListBoxItem id="egg">Egg Salad</ListBoxItem>
  <ListBoxItem id="ham">Ham</ListBoxItem>
</ListBox>

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

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

Links#

By default, interacting with an item in a ListBox 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.

<ListBox aria-label="Links">
  <ListBoxItem href="https://adobe.com/" target="_blank">Adobe</ListBoxItem>
  <ListBoxItem href="https://apple.com/" target="_blank">Apple</ListBoxItem>
  <ListBoxItem href="https://google.com/" target="_blank">Google</ListBoxItem>
  <ListBoxItem href="https://microsoft.com/" target="_blank">
    Microsoft
  </ListBoxItem>
</ListBox>

<ListBox aria-label="Links">
  <ListBoxItem href="https://adobe.com/" target="_blank">
    Adobe
  </ListBoxItem>
  <ListBoxItem href="https://apple.com/" target="_blank">
    Apple
  </ListBoxItem>
  <ListBoxItem href="https://google.com/" target="_blank">
    Google
  </ListBoxItem>
  <ListBoxItem
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </ListBoxItem>
</ListBox>

<ListBox aria-label="Links">
  <ListBoxItem
    href="https://adobe.com/"
    target="_blank"
  >
    Adobe
  </ListBoxItem>
  <ListBoxItem
    href="https://apple.com/"
    target="_blank"
  >
    Apple
  </ListBoxItem>
  <ListBoxItem
    href="https://google.com/"
    target="_blank"
  >
    Google
  </ListBoxItem>
  <ListBoxItem
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </ListBoxItem>
</ListBox>

By default, link items in a ListBox are not selectable, and only perform navigation when the user interacts with them. However, with the "replace" selection behavior, items will be selected when single clicking or pressing the Space key, and navigate to the link when double clicking or pressing the Enter key.

<ListBox
  aria-label="Links"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <ListBoxItem href="https://adobe.com/" target="_blank">Adobe</ListBoxItem>
  <ListBoxItem href="https://apple.com/" target="_blank">Apple</ListBoxItem>
  <ListBoxItem href="https://google.com/" target="_blank">Google</ListBoxItem>
  <ListBoxItem href="https://microsoft.com/" target="_blank">
    Microsoft
  </ListBoxItem>
</ListBox>

<ListBox
  aria-label="Links"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <ListBoxItem href="https://adobe.com/" target="_blank">
    Adobe
  </ListBoxItem>
  <ListBoxItem href="https://apple.com/" target="_blank">
    Apple
  </ListBoxItem>
  <ListBoxItem href="https://google.com/" target="_blank">
    Google
  </ListBoxItem>
  <ListBoxItem
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </ListBoxItem>
</ListBox>

<ListBox
  aria-label="Links"
  selectionMode="multiple"
  selectionBehavior="replace"
>
  <ListBoxItem
    href="https://adobe.com/"
    target="_blank"
  >
    Adobe
  </ListBoxItem>
  <ListBoxItem
    href="https://apple.com/"
    target="_blank"
  >
    Apple
  </ListBoxItem>
  <ListBoxItem
    href="https://google.com/"
    target="_blank"
  >
    Google
  </ListBoxItem>
  <ListBoxItem
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </ListBoxItem>
</ListBox>

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#

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>
    <ListBoxItem id="lettuce">Lettuce</ListBoxItem>
    <ListBoxItem id="tomato">Tomato</ListBoxItem>
    <ListBoxItem id="onion">Onion</ListBoxItem>
  </Section>
  <Section>
    <Header>Protein</Header>
    <ListBoxItem id="ham">Ham</ListBoxItem>
    <ListBoxItem id="tuna">Tuna</ListBoxItem>
    <ListBoxItem id="tofu">Tofu</ListBoxItem>
  </Section>
  <Section>
    <Header>Condiments</Header>
    <ListBoxItem id="mayo">Mayonaise</ListBoxItem>
    <ListBoxItem id="mustard">Mustard</ListBoxItem>
    <ListBoxItem id="ranch">Ranch</ListBoxItem>
  </Section>
</ListBox>

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

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

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

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

.react-aria-ListBox {
  .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-ListBox {
  .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-ListBox {
  .react-aria-Section:not(:first-child) {
    margin-top: 12px;
  }

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

Dynamic items#

The above example shows sections with static items. Sections can also be populated from a hierarchical 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 => <ListBoxItem>{item.name}</ListBoxItem>}
          </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) => (
              <ListBoxItem>{item.name}</ListBoxItem>
            )}
          </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) => (
              <ListBoxItem>
                {item
                  .name}
              </ListBoxItem>
            )}
          </Collection>
        </Section>
      )}
    </ListBox>
  );
}

Accessibility#

Sections without a <Header> must provide an aria-label for accessibility.

Text slots#

By default, items in a ListBox are labeled by their text contents for accessibility. Items 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. For these cases, see GridList instead.

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

<ListBox aria-label="Permissions" selectionMode="single">
  <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>
</ListBox>

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

<ListBox aria-label="Permissions" selectionMode="single">
  <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>
</ListBox>

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

<ListBox
  aria-label="Permissions"
  selectionMode="single"
>
  <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>
</ListBox>

.react-aria-ListBoxItem {
  [slot=label] {
    font-weight: bold;
  }

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

.react-aria-ListBoxItem {
  [slot=label] {
    font-weight: bold;
  }

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

.react-aria-ListBoxItem {
  [slot=label] {
    font-weight: bold;
  }

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

Layouts#

By default, ListBox expects items to be arranged in a vertical stack, and implements keyboard navigation and drag and drop accordingly. The layout and orientation props can be used to change this behavior, allowing you to build horizontal and vertical stacks and grids.

Horizontal stack#

This example displays a horizontal list of cards. The left and right arrow keys can be used to navigate between the items.

<ListBox
  aria-label="Albums"
  orientation="horizontal"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  orientation="horizontal"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  orientation="horizontal"  items={albums}
  selectionMode="multiple"
>
  {(item) => (
    <ListBoxItem
      textValue={item
        .title}
    >
      <img
        src={item
          .image}
        alt=""
      />
      <Text slot="label">
        {item.title}
      </Text>
      <Text slot="description">
        {item.artist}
      </Text>
    </ListBoxItem>
  )}
</ListBox>

.react-aria-ListBox[data-orientation=horizontal],
.react-aria-ListBox[data-layout=grid] {
  flex-direction: row;
  width: fit-content;
  max-width: 100%;
  padding: 4px;

  .react-aria-ListBoxItem {
    position: relative;
    margin: 0;
    padding: 4px;

    & img {
      object-fit: cover;
      aspect-ratio: 1/1;
      max-width: 150px;
      margin-bottom: 4px;
      border-radius: 4px;
      transition: box-shadow 200ms;
    }

    &[data-hovered] {
      & img {
        box-shadow: 0 0 8px rgb(from slateblue r g b / 0.5);
      }
    }

    &[data-selected] {
      background: none;
      color: inherit;

      & img {
        box-shadow: 0 0 12px rgb(from slateblue r g b / 0.8);
      }

      &:after {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 8px;
        right: 8px;
        background: var(--highlight-background);
        border: 2px solid var(--highlight-foreground);
        color: var(--highlight-foreground);
        width: 22px;
        height: 22px;
        border-radius: 22px;
        box-sizing: border-box;
        font-size: 14px;
        line-height: 1em;
        display: flex;
        align-items: center;
        justify-content: center;
        box-shadow: 0 0 8px rgb(0 0 0 / .5);
      }
    }
  }
}

.react-aria-ListBox[data-orientation=horizontal],
.react-aria-ListBox[data-layout=grid] {
  flex-direction: row;
  width: fit-content;
  max-width: 100%;
  padding: 4px;

  .react-aria-ListBoxItem {
    position: relative;
    margin: 0;
    padding: 4px;

    & img {
      object-fit: cover;
      aspect-ratio: 1/1;
      max-width: 150px;
      margin-bottom: 4px;
      border-radius: 4px;
      transition: box-shadow 200ms;
    }

    &[data-hovered] {
      & img {
        box-shadow: 0 0 8px rgb(from slateblue r g b / 0.5);
      }
    }

    &[data-selected] {
      background: none;
      color: inherit;

      & img {
        box-shadow: 0 0 12px rgb(from slateblue r g b / 0.8);
      }

      &:after {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 8px;
        right: 8px;
        background: var(--highlight-background);
        border: 2px solid var(--highlight-foreground);
        color: var(--highlight-foreground);
        width: 22px;
        height: 22px;
        border-radius: 22px;
        box-sizing: border-box;
        font-size: 14px;
        line-height: 1em;
        display: flex;
        align-items: center;
        justify-content: center;
        box-shadow: 0 0 8px rgb(0 0 0 / .5);
      }
    }
  }
}

.react-aria-ListBox[data-orientation=horizontal],
.react-aria-ListBox[data-layout=grid] {
  flex-direction: row;
  width: fit-content;
  max-width: 100%;
  padding: 4px;

  .react-aria-ListBoxItem {
    position: relative;
    margin: 0;
    padding: 4px;

    & img {
      object-fit: cover;
      aspect-ratio: 1/1;
      max-width: 150px;
      margin-bottom: 4px;
      border-radius: 4px;
      transition: box-shadow 200ms;
    }

    &[data-hovered] {
      & img {
        box-shadow: 0 0 8px rgb(from slateblue r g b / 0.5);
      }
    }

    &[data-selected] {
      background: none;
      color: inherit;

      & img {
        box-shadow: 0 0 12px rgb(from slateblue r g b / 0.8);
      }

      &:after {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 8px;
        right: 8px;
        background: var(--highlight-background);
        border: 2px solid var(--highlight-foreground);
        color: var(--highlight-foreground);
        width: 22px;
        height: 22px;
        border-radius: 22px;
        box-sizing: border-box;
        font-size: 14px;
        line-height: 1em;
        display: flex;
        align-items: center;
        justify-content: center;
        box-shadow: 0 0 8px rgb(0 0 0 / .5);
      }
    }
  }
}

Vertical grid#

The layout prop can be set to "grid" to enable two-dimensional keyboard navigation. By default, the grid scrolls vertically. The left, right, up, and down arrow keys can be used to navigate between the cards in this example.

<ListBox
  aria-label="Albums"
  layout="grid"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  layout="grid"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  layout="grid"  items={albums}
  selectionMode="multiple"
>
  {(item) => (
    <ListBoxItem
      textValue={item
        .title}
    >
      <img
        src={item
          .image}
        alt=""
      />
      <Text slot="label">
        {item.title}
      </Text>
      <Text slot="description">
        {item.artist}
      </Text>
    </ListBoxItem>
  )}
</ListBox>

.react-aria-ListBox[data-layout=grid] {
  display: grid;
  grid-template-columns: 1fr 1fr;
  scrollbar-gutter: stable;
}

.react-aria-ListBox[data-layout=grid] {
  display: grid;
  grid-template-columns: 1fr 1fr;
  scrollbar-gutter: stable;
}

.react-aria-ListBox[data-layout=grid] {
  display: grid;
  grid-template-columns: 1fr 1fr;
  scrollbar-gutter: stable;
}

Horizontal grid#

The layout="grid" and orientation="horizontal" props can be combined to build a two dimensional grid where the items are grouped into columns, and the grid scrolls horizontally.

<ListBox
  aria-label="Albums"
  layout="grid"
  orientation="horizontal"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  layout="grid"
  orientation="horizontal"  items={albums}
  selectionMode="multiple">
  {item => (
    <ListBoxItem textValue={item.title}>
      <img src={item.image} alt="" />
      <Text slot="label">{item.title}</Text>
      <Text slot="description">{item.artist}</Text>
    </ListBoxItem>
  )}
</ListBox>

<ListBox
  aria-label="Albums"
  layout="grid"
  orientation="horizontal"  items={albums}
  selectionMode="multiple"
>
  {(item) => (
    <ListBoxItem
      textValue={item
        .title}
    >
      <img
        src={item
          .image}
        alt=""
      />
      <Text slot="label">
        {item.title}
      </Text>
      <Text slot="description">
        {item.artist}
      </Text>
    </ListBoxItem>
  )}
</ListBox>

.react-aria-ListBox[data-layout=grid][data-orientation=horizontal] {
  width: 100%;
  max-width: none;
  display: grid;
  grid-auto-flow: column;
  grid-template-rows: 58px 58px;
  grid-template-columns: none;
  grid-auto-columns: 250px;
  max-height: 200px;
  gap: 8px;

  .react-aria-ListBoxItem {
    display: grid;
    grid-template-areas: "image ."
                         "image title"
                         "image description"
                         "image .";
    grid-template-columns: auto 1fr;
    grid-template-rows: 1fr auto auto 1fr;
    column-gap: 8px;

    & img {
      width: 50px;
      height: 50px;
      grid-area: image;
      margin-bottom: 0;
    }

    [slot=label] {
      grid-area: title;
    }

    [slot=description] {
      grid-area: description;
    }
  }
}

.react-aria-ListBox[data-layout=grid][data-orientation=horizontal] {
  width: 100%;
  max-width: none;
  display: grid;
  grid-auto-flow: column;
  grid-template-rows: 58px 58px;
  grid-template-columns: none;
  grid-auto-columns: 250px;
  max-height: 200px;
  gap: 8px;

  .react-aria-ListBoxItem {
    display: grid;
    grid-template-areas: "image ."
                         "image title"
                         "image description"
                         "image .";
    grid-template-columns: auto 1fr;
    grid-template-rows: 1fr auto auto 1fr;
    column-gap: 8px;

    & img {
      width: 50px;
      height: 50px;
      grid-area: image;
      margin-bottom: 0;
    }

    [slot=label] {
      grid-area: title;
    }

    [slot=description] {
      grid-area: description;
    }
  }
}

.react-aria-ListBox[data-layout=grid][data-orientation=horizontal] {
  width: 100%;
  max-width: none;
  display: grid;
  grid-auto-flow: column;
  grid-template-rows: 58px 58px;
  grid-template-columns: none;
  grid-auto-columns: 250px;
  max-height: 200px;
  gap: 8px;

  .react-aria-ListBoxItem {
    display: grid;
    grid-template-areas: "image ."
                         "image title"
                         "image description"
                         "image .";
    grid-template-columns: auto 1fr;
    grid-template-rows: 1fr auto auto 1fr;
    column-gap: 8px;

    & img {
      width: 50px;
      height: 50px;
      grid-area: image;
      margin-bottom: 0;
    }

    [slot=label] {
      grid-area: title;
    }

    [slot=description] {
      grid-area: description;
    }
  }
}

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

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) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
    </ListBox>
  );
}

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

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

Disabled items#

A ListBoxItem can be disabled with the isDisabled prop. Disabled items are not focusable, selectable, or keyboard navigable.

<ListBox
  aria-label="Choose sandwich contents with disabled items"
  selectionMode="multiple">
  <ListBoxItem>Lettuce</ListBoxItem>
  <ListBoxItem>Tomato</ListBoxItem>
  <ListBoxItem>Cheese</ListBoxItem>
  <ListBoxItem isDisabled>Tuna Salad</ListBoxItem>  <ListBoxItem>Egg Salad</ListBoxItem>
  <ListBoxItem>Ham</ListBoxItem>
</ListBox>

<ListBox
  aria-label="Choose sandwich contents with disabled items"
  selectionMode="multiple">
  <ListBoxItem>Lettuce</ListBoxItem>
  <ListBoxItem>Tomato</ListBoxItem>
  <ListBoxItem>Cheese</ListBoxItem>
  <ListBoxItem isDisabled>Tuna Salad</ListBoxItem>  <ListBoxItem>Egg Salad</ListBoxItem>
  <ListBoxItem>Ham</ListBoxItem>
</ListBox>

<ListBox
  aria-label="Choose sandwich contents with disabled items"
  selectionMode="multiple"
>
  <ListBoxItem>
    Lettuce
  </ListBoxItem>
  <ListBoxItem>
    Tomato
  </ListBoxItem>
  <ListBoxItem>
    Cheese
  </ListBoxItem>
  <ListBoxItem
    isDisabled
  >
    Tuna Salad
  </ListBoxItem>  <ListBoxItem>
    Egg Salad
  </ListBoxItem>
  <ListBoxItem>
    Ham
  </ListBoxItem>
</ListBox>

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

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

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

In dynamic collections, it may be more convenient to use the disabledKeys prop at the ListBox level instead of isDisabled on individual items. 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 for more details). An item is considered disabled if its id exists in disabledKeys or if it has isDisabled.

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 with disabledKeys"
      items={options}
      selectionMode="single"
      disabledKeys={[4, 6]}    >
      {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
    </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 with disabledKeys"
      items={options}
      selectionMode="single"
      disabledKeys={[4, 6]}    >
      {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
    </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 with disabledKeys"
      items={options}
      selectionMode="single"
      disabledKeys={[
        4,
        6
      ]}    >
      {(item) => (
        <ListBoxItem>
          {item.name}
        </ListBoxItem>
      )}
    </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>

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

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

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

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) => <ListBoxItem>{item.name}</ListBoxItem>}
    </ListBox>
  );
}