Collection components

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

Introduction#

There are many components that 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.

There are many ways one could design an API for components like this: JSX children, a list of option objects, or a datasource object. Selection, and other states like disabled, could be passed in to each item, or as a top-level prop. Each of these has various tradeoffs. This page describes how we do it in React Spectrum, and covers some of these tradeoffs in detail.

Design goals#

Our main design goal was to provide a consistent API across many types of collection components that is easy to learn, performant on large collections, and extensible for advanced features. Some of the use-cases we considered were:

Static data
Dynamic data
Async loading
Sections/groups of data from a single source
Sections from different sources
Single and multiple selection (controlled and uncontrolled)
Controlled and uncontrolled expanded states for components like trees and accordions
Marking items as selected, expanded, disabled, etc. prior to loading them from a server
Drag and drop of items
Virtualization for large collections
Infinite scrolling to load more items on demand

Static collections#

React Spectrum implements a JSX-based API for defining collections. This allows an intuitive way to provide items, which can contain rich rendering, and various options as props. Building hierarchical collections, e.g. sections, or a tree of items is also very natural in JSX.

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.

A simple static collection could be constructed as in the following example.

<Menu>
  <Item>Open</Item>
  <Item>Edit</Item>
  <Item>Delete</Item>
</Menu>

<Menu>
  <Item>Open</Item>
  <Item>Edit</Item>
  <Item>Delete</Item>
</Menu>

<Menu>
  <Item>Open</Item>
  <Item>Edit</Item>
  <Item>Delete</Item>
</Menu>

Sections#

Sections or groups of items can be constructed by wrapping the items as needed.

<ListBox>
  <Section title="People">
    <Item>David</Item>
    <Item>Sam</Item>
    <Item>Jane</Item>
  </Section>
  <Section title="Animals">
    <Item>Aardvark</Item>
    <Item>Kangaroo</Item>
    <Item>Snake</Item>
  </Section>
</ListBox>

<ListBox>
  <Section title="People">
    <Item>David</Item>
    <Item>Sam</Item>
    <Item>Jane</Item>
  </Section>
  <Section title="Animals">
    <Item>Aardvark</Item>
    <Item>Kangaroo</Item>
    <Item>Snake</Item>
  </Section>
</ListBox>

<ListBox>
  <Section title="People">
    <Item>David</Item>
    <Item>Sam</Item>
    <Item>Jane</Item>
  </Section>
  <Section title="Animals">
    <Item>
      Aardvark
    </Item>
    <Item>
      Kangaroo
    </Item>
    <Item>Snake</Item>
  </Section>
</ListBox>

The <Item> and <Section> components are shared between many collection components. This ensures that they have a consistent interface that can be learned once and applied everywhere.

<Item> and <Section> only define the data for the items and sections, not the rendering, visual appearance, or behavior. This is up to the individual collection component (e.g. Menu or ListBox) to implement.

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 Spectrum 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 => <Item>{item.name}</Item>}
</ListBox>

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

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

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

<ListBox
  items={animals}
>
  {(item) => (
    <Item>
      {item.name}
    </Item>
  )}
</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 an <Item>.

Unique keys#

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

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

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

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

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

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

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

Note that if you do specify a custom key on each Item using the key prop, React will convert the provided key to a string. As a result, all the collection component's key related event handlers and props (e.g. onSelectionChange, selectedKey(s)) will expect and return strings. If you forgo specifying a key on the Item and instead rely on the id or key being defined in your items array, the key related event handlers and props will match what you have in your items array. See the Selection docs for more info.

Why not array map?#

You may be wondering why we didn't use animals.map in this example. In fact, you can do this if you want and it will work, but it will not be as performant.

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

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

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

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

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

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

Using the items prop and providing a render function allows React Spectrum 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 useListBox 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) => <Item key={item.name}>{item.name}</Item>}
</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) => <Item key={item.name}>{item.name}</Item>}
</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) => (
    <Item
      key={item.name}
    >
      {item.name}
    </Item>
  )}
</ListBox>

Sections#

Sections can be built by returning a <Section> instead of an <Item> item from the top-level item renderer. Sections also support an items prop and a renderer function for their children.

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

<Picker items={sections}>
  {section =>
    <Section key={section.name} title={section.name} items={section.items}>
      {item => <Item key={item.name}>{item.name}</Item>}
    </Section>
  }
</Picker>

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

<Picker items={sections}>
  {(section) => (
    <Section
      key={section.name}
      title={section.name}
      items={section.items}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </Section>
  )}
</Picker>

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

<Picker
  items={sections}
>
  {(section) => (
    <Section
      key={section
        .name}
      title={section
        .name}
      items={section
        .items}
    >
      {(item) => (
        <Item
          key={item
            .name}
        >
          {item.name}
        </Item>
      )}
    </Section>
  )}
</Picker>

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.

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 title={node.value.name} items={node.children}>
      {(node) => <Item>{node.value.name}</Item>}
    </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
      title={node.value.name}
      items={node.children}
    >
      {(node) => <Item>{node.value.name}</Item>}
    </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
      title={node.value
        .name}
      items={node
        .children}
    >
      {(node) => (
        <Item>
          {node.value
            .name}
        </Item>
      )}
    </Section>
  )}
</ListBox>

Asynchronous loading#

Many collection components support loading data asynchronously. This is supported by passing an isLoading prop, which is true while the data is loading. Once the data is loaded, isLoading should be set to false, and the items prop should be set to the loaded data.

The useAsyncList hook from @react-stately/data 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.

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

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 };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list.isLoading}
>
  {(item) => <Item key={item.name}>{item.name}</Item>}
</Picker>

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 };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list.isLoading}
>
  {(item) => <Item key={item.name}>{item.name}</Item>}
</Picker>

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
    };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list
    .isLoading}
>
  {(item) => (
    <Item
      key={item.name}
    >
      {item.name}
    </Item>
  )}
</Picker>

Infinite loading#

The useAsyncList hook also supports paginated data, which is common in many APIs to avoid loading too many items at once. This is accomplished by returning a cursor in addition to items from the load function. When the loadMore method is called, the cursor is passed back to your load function, which you can use to determine the URL for the next page. The onLoadMore prop supported by many collection components notifies you when you should load more data as the user scrolls.

This example expands on the previous one to support infinite scrolling through all known Pokemon.

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load({ signal, cursor }) {
    // If no cursor is available, then we're loading the first page.
    // Otherwise, the cursor is the next URL to load, as returned from the previous page.
    let res = await fetch(cursor || 'https://pokeapi.co/api/v2/pokemon', {
      signal
    });
    let json = await res.json();
    return {
      items: json.results,
      cursor: json.next
    };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list.isLoading}
  onLoadMore={list.loadMore}
>
  {(item) => <Item key={item.name}>{item.name}</Item>}
</Picker>

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load({ signal, cursor }) {
    // If no cursor is available, then we're loading the first page.
    // Otherwise, the cursor is the next URL to load, as returned from the previous page.
    let res = await fetch(
      cursor || 'https://pokeapi.co/api/v2/pokemon',
      { signal }
    );
    let json = await res.json();
    return {
      items: json.results,
      cursor: json.next
    };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list.isLoading}
  onLoadMore={list.loadMore}
>
  {(item) => <Item key={item.name}>{item.name}</Item>}
</Picker>

import {useAsyncList} from 'react-stately';

let list = useAsyncList({
  async load(
    { signal, cursor }
  ) {
    // If no cursor is available, then we're loading the first page.
    // Otherwise, the cursor is the next URL to load, as returned from the previous page.
    let res =
      await fetch(
        cursor ||
          'https://pokeapi.co/api/v2/pokemon',
        { signal }
      );
    let json = await res
      .json();
    return {
      items:
        json.results,
      cursor: json.next
    };
  }
});

<Picker
  label="Pick a Pokemon"
  items={list.items}
  isLoading={list
    .isLoading}
  onLoadMore={list
    .loadMore}
>
  {(item) => (
    <Item
      key={item.name}
    >
      {item.name}
    </Item>
  )}
</Picker>

Item<T>(
  (props: ItemProps<T>
)): ReactElement

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.
`href`	`string`	A URL to link to. See MDN.
`target`	`HTMLAttributeAnchorTarget`	The target window for the link. See MDN.
`rel`	`string`	The relationship between the linked resource and the current page. See MDN.
`download`	`boolean \| string`	Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
`ping`	`string`	A space-separated list of URLs to ping when the link is followed. See MDN.
`referrerPolicy`	`HTMLAttributeReferrerPolicy`	How much of the referrer to send when following the link. See MDN.

Section<T>(
  (props: SectionProps<T>
)): ReactElement

Name	Type	Description
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>>

(
  (item: T
)) => ItemElement<T>

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>

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.