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.

Introduction#

Many React Aria components display a collection of items of some kind. For example, lists, menus, selects, tables, trees, and grids. These collections can usually be navigated with the keyboard using arrow keys, and many have some form of selection. Many support loading data asynchronously, updating that data over time, virtualized scrolling for performance with large collections, and more.

React Aria implements a JSX-based API for defining collections. This is an intuitive way to provide items with rich contents and various options as props. Building hierarchical collections, e.g. sections, or a tree of items is also very natural in JSX. React Aria provides a consistent API across many types of collection components that is easy to learn, performant with large collections, and extensible for advanced features.

Static collections#

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

<Menu>
  <MenuItem>Open</MenuItem>
  <MenuItem>Edit</MenuItem>
  <MenuItem>Delete</MenuItem>
</Menu>

<Menu>
  <MenuItem>Open</MenuItem>
  <MenuItem>Edit</MenuItem>
  <MenuItem>Delete</MenuItem>
</Menu>

<Menu>
  <MenuItem>
    Open
  </MenuItem>
  <MenuItem>
    Edit
  </MenuItem>
  <MenuItem>
    Delete
  </MenuItem>
</Menu>

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.

<Menu>
  <Section>
    <Header>Styles</Header>
    <MenuItem>Bold</MenuItem>
    <MenuItem>Underline</MenuItem>
  </Section>
  <Section>
    <Header>Align</Header>
    <MenuItem>Left</MenuItem>
    <MenuItem>Middle</MenuItem>
    <MenuItem>Right</MenuItem>
  </Section>
</Menu>

<Menu>
  <Section>
    <Header>Styles</Header>
    <MenuItem>Bold</MenuItem>
    <MenuItem>Underline</MenuItem>
  </Section>
  <Section>
    <Header>Align</Header>
    <MenuItem>Left</MenuItem>
    <MenuItem>Middle</MenuItem>
    <MenuItem>Right</MenuItem>
  </Section>
</Menu>

<Menu>
  <Section>
    <Header>
      Styles
    </Header>
    <MenuItem>
      Bold
    </MenuItem>
    <MenuItem>
      Underline
    </MenuItem>
  </Section>
  <Section>
    <Header>
      Align
    </Header>
    <MenuItem>
      Left
    </MenuItem>
    <MenuItem>
      Middle
    </MenuItem>
    <MenuItem>
      Right
    </MenuItem>
  </Section>
</Menu>

Dynamic collections#

Static collections are great when the items never change, but how about dynamic data? A dynamic collection is a collection that is based on 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.

React Aria implements a JSX-based interface for dynamic collections, which maps over your data and applies a function for each item to render it. The following example shows how a collection can be rendered based on dynamic data, stored in React state.

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

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

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

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

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

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

As you can see, the items are passed to the items prop of the top-level component, which iterates over each item and calls the function passed as children to the component. The item object is passed to the function, which returns a <ListBoxItem>.

Unique ids#

All items in a collection must have a unique id, which is used to determine what items in the collection changed when updates occur. By default, React Aria looks for an id property on each item object, which is often returned from a database. You can also specify a custom id on each item element using the id prop. For example, if all animals in the example had a unique name property, then each item's id could be set to item.name to use it as the unique id.

let [animals, setAnimals] = useState([
  {name: 'Aardvark'},
  {name: 'Kangaroo'},
  {name: 'Snake'}
]);

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

let [animals, setAnimals] = useState([
  { name: 'Aardvark' },
  { name: 'Kangaroo' },
  { name: 'Snake' }
]);

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

let [
  animals,
  setAnimals
] = useState([
  { name: 'Aardvark' },
  { name: 'Kangaroo' },
  { name: 'Snake' }
]);

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

Why not array map?#

You may be wondering why we didn't use animals.map in this example. In fact, this works just fine, but it's less performant, and you must remember to provide both a React key and an id prop.

let [animals, setAnimals] = useState([
  {name: 'Aardvark'},
  {name: 'Kangaroo'},
  {name: 'Snake'}
]);

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

let [animals, setAnimals] = useState([
  { name: 'Aardvark' },
  { name: 'Kangaroo' },
  { name: 'Snake' }
]);

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

let [
  animals,
  setAnimals
] = useState([
  { name: 'Aardvark' },
  { name: 'Kangaroo' },
  { name: 'Snake' }
]);

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

Using the items prop and providing a render function allows React Aria to automatically cache the results of rendering each item and avoid re-rendering all items in the collection when only one of them changes. This has big performance benefits for large collections.

Updating data#

When you need to update the data to add, remove, or change an item, you can do so using a standard React state update.

Important: all items passed to a collection component must be immutable. Changing a property on an item, or calling array.push() or other mutating methods will not work as expected.

The useListData hook can be used to manage the data and state for a list of items, and update it over time. It will also handle removing items from the selection state when they are removed from the list. See the useListData docs for more details.

The following example shows how you might append a new item to the list.

import {useListData} from 'react-stately';

let list = useListData({
  initialItems: [
    { name: 'Aardvark' },
    { name: 'Kangaroo' },
    { name: 'Snake' }
  ],
  initialSelectedKeys: ['Kangaroo'],
  getKey: (item) => item.name
});

function addAnimal(name) {
  list.append({ name });
}

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

import {useListData} from 'react-stately';

let list = useListData({
  initialItems: [
    { name: 'Aardvark' },
    { name: 'Kangaroo' },
    { name: 'Snake' }
  ],
  initialSelectedKeys: ['Kangaroo'],
  getKey: (item) => item.name
});

function addAnimal(name) {
  list.append({ name });
}

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

import {useListData} from 'react-stately';

let list = useListData({
  initialItems: [
    { name: 'Aardvark' },
    { name: 'Kangaroo' },
    { name: 'Snake' }
  ],
  initialSelectedKeys: [
    'Kangaroo'
  ],
  getKey: (item) =>
    item.name
});

function addAnimal(
  name
) {
  list.append({ name });
}

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

Note that useListData is a convenience hook, not a requirement. You can use any state management library to manage collection items.

Sections#

Sections can be built by returning a <Section> instead of an item from the top-level item renderer. Sections also support an items prop and a render function for their children. If the section also has a header, the Collection component can be used to render the child items.

let [sections, setSections] = useState([
  {
    name: 'People',
    items: [
      {name: 'David'},
      {name: 'Same'},
      {name: 'Jane'}
    ]
  },
  {
    name: 'Animals',
    items: [
      {name: 'Aardvark'},
      {name: 'Kangaroo'},
      {name: 'Snake'}
    ]
  }
]);

<ListBox items={sections}>
  {section =>
    <Section id={section.name}>
      <Header>{section.name}</Header>
      <Collection items={section.children}>
        {item => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
      </Collection>
    </Section>
  }
</ListBox>

let [sections, setSections] = useState([
  {
    name: 'People',
    items: [
      { name: 'David' },
      { name: 'Same' },
      { name: 'Jane' }
    ]
  },
  {
    name: 'Animals',
    items: [
      { name: 'Aardvark' },
      { name: 'Kangaroo' },
      { name: 'Snake' }
    ]
  }
]);

<ListBox items={sections}>
  {(section) => (
    <Section id={section.name}>
      <Header>{section.name}</Header>
      <Collection items={section.children}>
        {(item) => (
          <ListBoxItem id={item.name}>
            {item.name}
          </ListBoxItem>
        )}
      </Collection>
    </Section>
  )}
</ListBox>

let [
  sections,
  setSections
] = useState([
  {
    name: 'People',
    items: [
      { name: 'David' },
      { name: 'Same' },
      { name: 'Jane' }
    ]
  },
  {
    name: 'Animals',
    items: [
      {
        name: 'Aardvark'
      },
      {
        name: 'Kangaroo'
      },
      { name: 'Snake' }
    ]
  }
]);

<ListBox
  items={sections}
>
  {(section) => (
    <Section
      id={section.name}
    >
      <Header>
        {section.name}
      </Header>
      <Collection
        items={section
          .children}
      >
        {(item) => (
          <ListBoxItem
            id={item
              .name}
          >
            {item.name}
          </ListBoxItem>
        )}
      </Collection>
    </Section>
  )}
</ListBox>

When updating nested data, be sure that all parent items change accordingly. Items are immutable, so don't use mutating methods like push, or replace a property on a parent item. Instead, copy the items that changed as needed.

useTreeData#

The useTreeData hook can be used to manage data and state for a tree of items. This is similar to useListData, but with support for heirarchical data. Like useListData, useTreeData will also handle automatically removing items from the selection when they are removed from the list. See the useTreeData docs for more details.

import {useTreeData} from 'react-stately';

let tree = useTreeData({
  initialItems: [
    {
      name: 'People',
      items: [
        { name: 'David' },
        { name: 'Sam' },
        { name: 'Jane' }
      ]
    },
    {
      name: 'Animals',
      items: [
        { name: 'Aardvark' },
        { name: 'Kangaroo' },
        { name: 'Snake' }
      ]
    }
  ],
  getKey: (item) => item.name,
  getChildren: (item) => item.items
});

function addPerson(name) {
  tree.append('People', { name });
}

<ListBox items={tree.items}>
  {(node) => (
    <Section id={section.name} items={node.children}>
      <Header>{section.name}</Header>
      <Collection items={section.children}>
        {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
      </Collection>
    </Section>
  )}
</ListBox>

import {useTreeData} from 'react-stately';

let tree = useTreeData({
  initialItems: [
    {
      name: 'People',
      items: [
        { name: 'David' },
        { name: 'Sam' },
        { name: 'Jane' }
      ]
    },
    {
      name: 'Animals',
      items: [
        { name: 'Aardvark' },
        { name: 'Kangaroo' },
        { name: 'Snake' }
      ]
    }
  ],
  getKey: (item) => item.name,
  getChildren: (item) => item.items
});

function addPerson(name) {
  tree.append('People', { name });
}

<ListBox items={tree.items}>
  {(node) => (
    <Section id={section.name} items={node.children}>
      <Header>{section.name}</Header>
      <Collection items={section.children}>
        {(item) => (
          <ListBoxItem id={item.name}>
            {item.name}
          </ListBoxItem>
        )}
      </Collection>
    </Section>
  )}
</ListBox>

import {useTreeData} from 'react-stately';

let tree = useTreeData({
  initialItems: [
    {
      name: 'People',
      items: [
        {
          name: 'David'
        },
        { name: 'Sam' },
        { name: 'Jane' }
      ]
    },
    {
      name: 'Animals',
      items: [
        {
          name:
            'Aardvark'
        },
        {
          name:
            'Kangaroo'
        },
        { name: 'Snake' }
      ]
    }
  ],
  getKey: (item) =>
    item.name,
  getChildren: (item) =>
    item.items
});

function addPerson(
  name
) {
  tree.append('People', {
    name
  });
}

<ListBox
  items={tree.items}
>
  {(node) => (
    <Section
      id={section.name}
      items={node
        .children}
    >
      <Header>
        {section.name}
      </Header>
      <Collection
        items={section
          .children}
      >
        {(item) => (
          <ListBoxItem
            id={item
              .name}
          >
            {item.name}
          </ListBoxItem>
        )}
      </Collection>
    </Section>
  )}
</ListBox>

Note that useTreeData is a utility hook, not a requirement. You can use any state management library to manage collection items.

Asynchronous loading#

The useAsyncList hook can be used to manage async data loading from an API. Pass a load function to useAsyncList, which returns the items to render. You can use whatever data fetching library you want, or the built-in fetch API. See the useAsyncList docs for more details.

This example fetches a list of Pokemon from an API and displays them in a Select.

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load({ signal }) {
    let res = await fetch('https://pokeapi.co/api/v2/pokemon', { signal });
    let json = await res.json();
    return { items: json.results };
  }
});

<Select>
  <Label>Pick a Pokemon</Label>
  <Button>
    <SelectValue />
  </Button>
  <Popover>
    <ListBox items={list.items}>
      {(item) => <ListBoxItem id={item.name}>{item.name}</ListBoxItem>}
    </ListBox>
  </Popover>
</Select>

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load({ signal }) {
    let res = await fetch(
      'https://pokeapi.co/api/v2/pokemon',
      { signal }
    );
    let json = await res.json();
    return { items: json.results };
  }
});

<Select>
  <Label>Pick a Pokemon</Label>
  <Button>
    <SelectValue />
  </Button>
  <Popover>
    <ListBox items={list.items}>
      {(item) => (
        <ListBoxItem id={item.name}>
          {item.name}
        </ListBoxItem>
      )}
    </ListBox>
  </Popover>
</Select>

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load(
    { signal }
  ) {
    let res =
      await fetch(
        'https://pokeapi.co/api/v2/pokemon',
        { signal }
      );
    let json = await res
      .json();
    return {
      items: json.results
    };
  }
});

<Select>
  <Label>
    Pick a Pokemon
  </Label>
  <Button>
    <SelectValue />
  </Button>
  <Popover>
    <ListBox
      items={list
        .items}
    >
      {(item) => (
        <ListBoxItem
          id={item
            .name}
        >
          {item.name}
        </ListBoxItem>
      )}
    </ListBox>
  </Popover>
</Select>

Note that useAsyncList is a convenience hook, not a requirement. You can use any state management or data loading library to manage collection items.

Hooks#

If you're using React Aria and React Stately hooks rather than components, the collection API is slightly different. See the React Stately collections documentation for more details.

Manages state for an immutable list data structure, and provides convenience methods to update the data over time.

useListData<T>(
  (options: ListOptions<T>
)): ListData<T>

Name	Type	Description
`initialItems`	`T[]`	Initial items in the list.
`initialSelectedKeys`	`'all' \| Iterable<Key>`	The keys for the initially selected items.
`initialFilterText`	`string`	The initial text to filter the list by.
`getKey`	`( (item: T )) => Key`	A function that returns a unique key for an item object.
`filter`	`( (item: T, , filterText: string )) => boolean`	A function that returns whether a item matches the current filter text.

string | number

Properties

Name	Type	Description
`items`	`T[]`	The items in the list.
`selectedKeys`	`Selection`	The keys of the currently selected items in the list.
`filterText`	`string`	The current filter text.

Methods

Method	Description
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys.
`setFilterText( (filterText: string )): void`	Sets the filter text.
`getItem( (key: Key )): T`	Gets an item from the list by key.
`insert( (index: number, , ...values: T[] )): void`	Inserts items into the list at the given index.
`insertBefore( (key: Key, , ...values: T[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: T[] )): void`	Inserts items into the list after the item at the given key.
`append( (...values: T[] )): void`	Appends items to the list.
`prepend( (...values: T[] )): void`	Prepends items to the list.
`remove( (...keys: Key[] )): void`	Removes items from the list by their keys.
`removeSelectedItems(): void`	Removes all items from the list that are currently in the set of selected items.
`move( (key: Key, , toIndex: number )): void`	Moves an item within the list.
`moveBefore( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items before a given key.
`moveAfter( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items after a given key.
`update( (key: Key, , newValue: T )): void`	Updates an item in the list.

'all' | Set<Key>

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

Name	Type	Description
`children`	`ReactNode \| ( (item: object )) => ReactNode`	The contents of the collection.
`dependencies`	`any[]`	Values that should invalidate the item cache when using dynamic collections.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

Manages state for an immutable tree data structure, and provides convenience methods to update the data over time.

useTreeData<T extends object>(
  (options: TreeOptions<T>
)): TreeData<T>

Name	Type	Description
`initialItems`	`object[]`	Initial root items in the tree.
`initialSelectedKeys`	`Iterable<Key>`	The keys for the initially selected items.
`getKey`	`( (item: object )) => Key`	A function that returns a unique key for an item object.
`getChildren`	`( (item: object )) => object[]`	A function that returns the children for an item object.

Properties

Name	Type	Description
`items`	`TreeNode<object>[]`	The root nodes in the tree.
`selectedKeys`	`Set<Key>`	The keys of the currently selected items in the tree.

Methods

Method	Description
`setSelectedKeys( (keys: Set<Key> )): void`	Sets the selected keys.
`getItem( (key: Key )): TreeNode<object>`	Gets a node from the tree by key.
`insert( parentKey: Key \| \| null, index: number, ...values: object[] ): void`	Inserts an item into a parent node as a child.
`insertBefore( (key: Key, , ...values: object[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: object[] )): void`	Inserts items into the list after the item at the given key.
`append( (parentKey: Key \| \| null, , ...values: object[] )): void`	Appends an item into a parent node as a child.
`prepend( (parentKey: Key \| \| null, , ...value: object[] )): void`	Prepends an item into a parent node as a child.
`remove( (...keys: Key[] )): void`	Removes an item from the tree by its key.
`removeSelectedItems(): void`	Removes all items from the tree that are currently in the set of selected items.
`move( key: Key, toParentKey: Key \| \| null, index: number ): void`	Moves an item within the tree.
`update( (key: Key, , newValue: object )): void`	Updates an item in the tree.

Name	Type	Description
`key`	`Key`	A unique key for the tree node.
`parentKey`	`Key`	The key of the parent node.
`value`	`object`	The value object for the tree node.
`children`	`TreeNode<object>[]`	Children of the tree node.

Manages state for an immutable async loaded list data structure, and provides convenience methods to update the data over time. Manages loading and error states, pagination, and sorting.

useAsyncList<T, C = string>(
  (options: AsyncListOptions<T, C>
)): AsyncListData<T>

Name	Type	Description
`load`	`AsyncListLoadFunction<T, C>`	A function that loads the data for the items in the list.
`initialSelectedKeys`	`Iterable<Key>`	The keys for the initially selected items.
`initialSortDescriptor`	`SortDescriptor`	The initial sort descriptor.
`initialFilterText`	`string`	The initial filter text.
`getKey`	`( (item: T )) => Key`	A function that returns a unique key for an item object.
`sort`	`AsyncListLoadFunction<T, C>`	An optional function that performs sorting. If not provided, then `sortDescriptor` is passed to the `load` function.

Name	Type	Description
`column`	`Key`	The key of the column to sort by.
`direction`	`SortDirection`	The direction to sort by.

'ascending' | 'descending'

(
  (state: AsyncListLoadOptions<T, C>
)) => AsyncListStateUpdate<T, C> | Promise<AsyncListStateUpdate<T, C>>

Name	Type	Description
`items`	`T[]`	The items currently in the list.
`selectedKeys`	`Selection`	The keys of the currently selected items in the list.
`sortDescriptor`	`SortDescriptor`	The current sort descriptor for the list.
`signal`	`AbortSignal`	An abort signal used to notify the load function that the request has been aborted.
`cursor`	`C`	The pagination cursor returned from the last page load.
`filterText`	`string`	The current filter text used to perform server side filtering.
`loadingState`	`LoadingState`	The current loading state of the list.

'loading'
  | 'sorting'
  | 'loadingMore'
  | 'error'
  | 'idle'
  | 'filtering'

Name	Type	Description
`items`	`Iterable<T>`	The new items to append to the list.
`selectedKeys`	`Iterable<Key>`	The keys to add to the selection.
`sortDescriptor`	`SortDescriptor`	The sort descriptor to set.
`cursor`	`C`	The pagination cursor to be used for the next page load.
`filterText`	`string`	The updated filter text for the list.

Properties

Name	Type	Description
`isLoading`	`boolean`	Whether data is currently being loaded.
`loadingState`	`LoadingState`	The current loading state for the list.
`items`	`T[]`	The items in the list.
`selectedKeys`	`Selection`	The keys of the currently selected items in the list.
`filterText`	`string`	The current filter text.
`error`	`Error`	If loading data failed, then this contains the error that occurred.
`sortDescriptor`	`SortDescriptor`	The current sort descriptor for the list.

Methods

Method	Description
`reload(): void`	Reloads the data in the list.
`loadMore(): void`	Loads the next page of data in the list.
`sort( (descriptor: SortDescriptor )): void`	Triggers sorting for the list.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys.
`setFilterText( (filterText: string )): void`	Sets the filter text.
`getItem( (key: Key )): T`	Gets an item from the list by key.
`insert( (index: number, , ...values: T[] )): void`	Inserts items into the list at the given index.
`insertBefore( (key: Key, , ...values: T[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: T[] )): void`	Inserts items into the list after the item at the given key.
`append( (...values: T[] )): void`	Appends items to the list.
`prepend( (...values: T[] )): void`	Prepends items to the list.
`remove( (...keys: Key[] )): void`	Removes items from the list by their keys.
`removeSelectedItems(): void`	Removes all items from the list that are currently in the set of selected items.
`move( (key: Key, , toIndex: number )): void`	Moves an item within the list.
`moveBefore( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items before a given key.
`moveAfter( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items after a given key.
`update( (key: Key, , newValue: T )): void`	Updates an item in the list.