Collections

Many components display a collection of items, and provide functionality such as keyboard navigation, selection, and more. React Aria has a consistent, compositional API to define the items displayed in these components.

Static collections

A static collection is a collection that does not change over time (e.g. hard coded). This is common for components like menus where the items are built into the application rather than user data.

import {MenuButton, MenuItem} from './Menu';

<MenuButton label="Menu">
  <MenuItem>Open</MenuItem>
  <MenuItem>Edit</MenuItem>
  <MenuItem>Delete</MenuItem>
</MenuButton>

Sections

Sections or groups of items can be constructed by wrapping the items in a section element. A <Header> can also be rendered within a section to provide a section title.

import {MenuButton, MenuItem, MenuSection} from './Menu';
import {Header} from 'react-aria-components';

<MenuButton label="Menu">
  <MenuSection>
    <Header>Styles</Header>
    <MenuItem>Bold</MenuItem>
    <MenuItem>Underline</MenuItem>
  </MenuSection>
  <MenuSection>
    <Header>Align</Header>
    <MenuItem>Left</MenuItem>
    <MenuItem>Middle</MenuItem>
    <MenuItem>Right</MenuItem>
  </MenuSection>
</MenuButton>

Dynamic collections

A dynamic collection is a collection that is based on external data, for example from an API. In addition, it may change over time as items are added, updated, or removed from the collection by a user.

Use the items prop to provide an array of objects, and a function to render each item as the children. This is similar to using array.map to render the children, but automatically memoizes the rendering of each item to improve performance.

import {ListBox, ListBoxItem} from './ListBox';
import {Button} from './Button';
import {useState} from 'react';

function Example() {
  let [animals, setAnimals] = useState([
    {id: 1, name: 'Aardvark'},
    {id: 2, name: 'Kangaroo'},
    {id: 3, name: 'Snake'}
  ]);

  let addItem = () => {
    setAnimals([
      ...animals,
      {id: animals.length + 1, name: 'Lion'}
    ]);
  };

  return (
    <div>
      <ListBox items={animals}>
        {item => <ListBoxItem>{item.name}</ListBoxItem>}
      </ListBox>
      <Button onPress={addItem} style={{marginTop: 8}}>Add item</Button>
    </div>
  );
}

Unique ids

All items in a collection must have a unique id, which is used for selection and to track item updates. By default, React Aria looks for an id property on each object in the items array. You can also specify an id prop when rendering each item. This example uses item.name as the id.

let animals = [
  {name: 'Aardvark'},
  {name: 'Kangaroo'},
  {name: 'Snake'}
];

<ListBox items={animals}>
  {item => (
    <ListBoxItem id={item.name}>
      {item.name}
    </ListBoxItem>
  )}
</ListBox>

Dependencies

Dynamic collections are automatically memoized to improve performance. Rendered item elements are cached based on the object identity of the list item. If rendering an item depends on additional external state, the dependencies prop must be provided. This invalidates rendered elements similar to dependencies in React's useMemo hook.

import {ListBox, ListBoxItem} from './ListBox';
import {Text} from 'react-aria-components';
import {ToggleButtonGroup} from './ToggleButtonGroup';
import {ToggleButton} from './ToggleButton';
import {useState} from 'react';

const items = [
  {id: 1, name: 'Charizard', type: 'Fire, Flying'},
  {id: 2, name: 'Blastoise', type: 'Water'},
  {id: 3, name: 'Venusaur', type: 'Grass, Poison'},
  {id: 4, name: 'Pikachu', type: 'Electric'}
];

export default function Example() {
  let [layout, setLayout] = useState('vertical');

  return (
    <div>
      <ToggleButtonGroup
        aria-label="Layout"
        selectedKeys={[layout]}
        onSelectionChange={keys => setLayout([...keys][0])}
        disallowEmptySelection
        style={{marginBottom: 8}}>
        <ToggleButton id="vertical">Vertical</ToggleButton>
        <ToggleButton id="horizontal">Horizontal</ToggleButton>
      </ToggleButtonGroup>
      <ListBox
        items={items}
        selectionMode="multiple"
        dependencies={[layout]}>
        {item => (
          <MyItem
            layout={layout}
            name={item.name}
            type={item.type} />
        )}
      </ListBox>
    </div>
  );
}

interface MyItemProps {
  layout: 'horizontal' | 'vertical',
  name: string,
  type: string
}

function MyItem(props: MyItemProps) {
  return (
    <ListBoxItem
      style={{
        display: 'flex',
        flexDirection: props.layout === 'horizontal' ? 'row' : 'column',
        justifyContent: 'space-between',
        alignItems: props.layout === 'horizontal' ? 'center' : 'start'
      }}>
      <Text slot="label">{props.name}</Text>
      <Text slot="description">{props.type}</Text>
    </ListBoxItem>
  );
}

Note that adding dependencies will result in the entire list being invalidated when a dependency changes. To avoid this and invalidate only an individual item, update the item object itself rather than accessing external state.

Combining collections

To combine multiple sources of data, or mix static and dynamic items, use the <Collection> component.

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

let animals = [
  {id: 1, species: 'Aardvark'},
  {id: 2, species: 'Kangaroo'},
  {id: 3, species: 'Snake'}
];

let people = [
  {id: 4, name: 'David'},
  {id: 5, name: 'Mike'},
  {id: 6, name: 'Jane'}
];

<ListBox>
  <ListBoxSection>
    <Header>Animals</Header>
    <Collection items={animals}>
      {item => <ListBoxItem id={item.species}>{item.species}</ListBoxItem>}
    </Collection>
  </ListBoxSection>
  <ListBoxSection>
    <Header>People</Header>
    <Collection items={people}>
      {item => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
    </Collection>
  </ListBoxSection>
</ListBox>

Asynchronous loading

Data can be loaded asynchronously using any data fetching library. useAsyncList is a built-in option.

Several components also support infinite scrolling by rendering a LoadMoreItem at the end of the list. These trigger loading of additional pages of items and display a loading spinner. Multiple load more items can be rendered at once, e.g. when loading multiple levels of a tree or sections in a list.

import {Collection, ListBoxLoadMoreItem} from 'react-aria-components';
import {ListBox, ListBoxItem} from './ListBox';
import {ProgressCircle} from './ProgressCircle';
import {useAsyncList} from 'react-stately';

interface Character {
  name: string
}

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

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <ListBox
      aria-label="Pick a Pokemon"
      selectionMode="single"
      renderEmptyState={() => (
        <ProgressCircle isIndeterminate aria-label="Loading..." />
      )}>
      <Collection items={list.items}>
        {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
      </Collection>
      <ListBoxLoadMoreItem
        onLoadMore={list.loadMore}
        isLoading={list.loadingState === 'loadingMore'}>
        <ProgressCircle isIndeterminate aria-label="Loading more..." />
      </ListBoxLoadMoreItem>
    </ListBox>
  );
}