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 hierarchical 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.

Virtualized scrolling#

Collection components like ListBox, GridList, and Table support virtualized scrolling, which is a performance optimization for large lists. Instead of rendering all items to the DOM at once, it only renders the visible items, reusing them as the user scrolls. This results in a small number of DOM elements being rendered, reducing memory usage and improving browser layout and rendering performance.

Collections can be virtualized by wrapping them in a <Virtualizer>, and providing a Layout object such as ListLayout or GridLayout. Layouts are responsible for determining the position of each item in the collection, and providing the list of visible items. When using a Virtualizer, all items are positioned by the Layout object, and CSS layout properties such as flexbox and grid do not apply.

import {Virtualizer, ListLayout} from 'react-aria-components';

let layout = useMemo(() => new ListLayout({
  rowHeight: 50
}), []);

<Virtualizer layout={layout}>
  <ListBox items={items}>
    {item => <ListBoxItem>{item}</ListBoxItem>}
  </ListBox>
</Virtualizer>

import {
  ListLayout,
  Virtualizer
} from 'react-aria-components';

let layout = useMemo(() =>
  new ListLayout({
    rowHeight: 50
  }), []);

<Virtualizer layout={layout}>
  <ListBox items={items}>
    {(item) => <ListBoxItem>{item}</ListBoxItem>}
  </ListBox>
</Virtualizer>

import {
  ListLayout,
  Virtualizer
} from 'react-aria-components';

let layout = useMemo(
  () =>
    new ListLayout({
      rowHeight: 50
    }),
  []
);

<Virtualizer
  layout={layout}
>
  <ListBox
    items={items}
  >
    {(item) => (
      <ListBoxItem>
        {item}
      </ListBoxItem>
    )}
  </ListBox>
</Virtualizer>

See the Virtualizer docs for more details.

Advanced: Custom collection renderers#

Internally, Virtualizer is powered by a CollectionRenderer. Collection components delegate to a CollectionRenderer to render their items and sections, and to handle keyboard navigation and drag and drop interactions. Collection renderers are provided via CollectionRendererContext. The default CollectionRenderer simply renders all items to the DOM, but this can be overridden to implement custom behavior. The API includes the following properties:

Name	Type	Description
`CollectionRoot`	`React.ComponentType<CollectionRootProps>`	A component that renders the root collection items.
`CollectionBranch`	`React.ComponentType<CollectionBranchProps>`	A component that renders the child collection items.
`isVirtualized`	`boolean`	Whether this is a virtualized collection.
`layoutDelegate`	`LayoutDelegate`	A delegate object that provides layout information for items in the collection.
`dropTargetDelegate`	`DropTargetDelegate`	A delegate object that provides drop targets for pointer coordinates within the collection.

The two required properties are CollectionRoot and CollectionBranch. These are React components that render the items at the root of a collection, and the children of a specific item respectively. See the Collection interface docs for details on the collection and item APIs.

import type {CollectionRenderer} from 'react-aria-components';
import {CollectionRendererContext} from 'react-aria-components';

const renderer: CollectionRenderer = {
  CollectionRoot({collection}) {
    let items = [];
    for (let item of collection) {
      items.push(item.render(item));
    }
    return items;
  },
  CollectionBranch({collection, parent}) {
    let items = [];
    for (let item of collection.getChildren(parent.key)) {
      items.push(item.render(item));
    }
    return items;
  }
};

<CollectionRendererContext.Provider value={renderer}>
  <ListBox>
    {/* ... */}
  </ListBox>
</CollectionRendererContext.Provider>

import type {CollectionRenderer} from 'react-aria-components';
import {CollectionRendererContext} from 'react-aria-components';

const renderer: CollectionRenderer = {
  CollectionRoot({ collection }) {
    let items = [];
    for (let item of collection) {
      items.push(item.render(item));
    }
    return items;
  },
  CollectionBranch({ collection, parent }) {
    let items = [];
    for (let item of collection.getChildren(parent.key)) {
      items.push(item.render(item));
    }
    return items;
  }
};

<CollectionRendererContext.Provider value={renderer}>
  <ListBox>
    {/* ... */}
  </ListBox>
</CollectionRendererContext.Provider>

import type {CollectionRenderer} from 'react-aria-components';
import {CollectionRendererContext} from 'react-aria-components';

const renderer:
  CollectionRenderer = {
    CollectionRoot(
      { collection }
    ) {
      let items = [];
      for (
        let item
          of collection
      ) {
        items.push(
          item.render(
            item
          )
        );
      }
      return items;
    },
    CollectionBranch(
      {
        collection,
        parent
      }
    ) {
      let items = [];
      for (
        let item
          of collection
            .getChildren(
              parent.key
            )
      ) {
        items.push(
          item.render(
            item
          )
        );
      }
      return items;
    }
  };

<CollectionRendererContext.Provider
  value={renderer}
>
  <ListBox>
    {/* ... */}
  </ListBox>
</CollectionRendererContext.Provider>

Important Requirements

The value passed to CollectionRendererContext must be memoized. Otherwise React will unmount and remount CollectionRoot and CollectionBranch on every render.
Additional DOM elements must have a valid ARIA role. Use role="presentation" for elements added only for styling purposes. Other elements must be valid within the ARIA pattern that the collection component follows.

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 \| undefined`	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
`items`	`Iterable<object>`	Item objects in the collection.
`children`	`ReactNode \| ( (item: object )) => ReactNode`	The contents of the collection.
`dependencies`	`ReadonlyArray<any>`	Values that should invalidate the item cache when using dynamic collections.
`idScope`	`Key`	A scope to prepend to all child item ids to ensure they are unique.
`addIdAndValue`	`boolean`	Whether to add `id` and `value` props to all child items.

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> \| undefined`	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.
`value`	`object`	The value object for the tree node.
`children`	`TreeNode<object>[] \| null`	Children of the tree node.
`parentKey`	`Key \| null`	The key of the parent 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, AsyncListLoadOptions<T, C> & {sortDescriptor: SortDescriptor }>`	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: S
)) => AsyncListStateUpdate<T, C> | Promise<AsyncListStateUpdate<T, C>>

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.

Name	Type	Description
`items`	`T[]`	The items currently in the list.
`selectedKeys`	`Selection`	The keys of the currently selected items in the list.
`signal`	`AbortSignal`	An abort signal used to notify the load function that the request has been aborted.
`sortDescriptor`	`SortDescriptor`	The current sort descriptor for the list.
`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'

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 \| undefined`	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.

A Virtualizer renders a scrollable collection of data using customizable layouts. It supports very large collections by only rendering visible items to the DOM, reusing them as the user scrolls.

Name	Type	Description
`children`	`ReactNode`	The child collection to virtualize (e.g. ListBox, GridList, or Table).
`layout`	`LayoutClass<O> \| ILayout<O>`	The layout object that determines the position and size of the visible elements.
`layoutOptions`	`O`	Options for the layout.

Extends: Partial

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, any> \| null`	The Virtualizer the layout is currently attached to.

Methods

Method	Description
`abstract getVisibleLayoutInfos( (rect: Rect )): LayoutInfo[]`	Returns an array of `LayoutInfo` objects which are inside the given rectangle. Should be implemented by subclasses.
`abstract getLayoutInfo( (key: Key )): LayoutInfo \| null`	Returns a `LayoutInfo` for the given key. Should be implemented by subclasses.
`abstract getContentSize(): Size`	Returns size of the content. By default, it returns virtualizer's size.
`shouldInvalidate( (newRect: Rect, , oldRect: Rect )): boolean`	Returns whether the layout should invalidate in response to visible rectangle changes. By default, it only invalidates when the virtualizer's size changes. Return true always to make the layout invalidate while scrolling (e.g. sticky headers).
`shouldInvalidateLayoutOptions( (newOptions: O, , oldOptions: O )): boolean`	Returns whether the layout should invalidate when the layout options change. By default it invalidates when the object identity changes. Override this method to optimize layout updates based on specific option changes.
`update( (invalidationContext: InvalidationContext<O> )): void`	This method allows the layout to perform any pre-computation it needs to in order to prepare LayoutInfos for retrieval. Called by the virtualizer before `getVisibleLayoutInfos` or `getLayoutInfo` are called.
`updateItemSize( (key: Key, , size: Size )): boolean`	Updates the size of the given item.
`getDropTargetLayoutInfo( (target: ItemDropTarget )): LayoutInfo`	Returns a `LayoutInfo` for the given drop target.
`useLayoutOptions(): O`

The Virtualizer class renders a scrollable collection of data using customizable layouts. It supports very large collections by only rendering visible views to the DOM, reusing them as you scroll. Virtualizer can present any type of view, including non-item views such as section headers and footers.

Virtualizer uses Layout objects to compute what views should be visible, and how to position and style them. This means that virtualizer can have its items arranged in a stack, a grid, a circle, or any other layout you can think of. The layout can be changed dynamically at runtime as well.

Layouts produce information on what views should appear in the virtualizer, but do not create the views themselves directly. It is the responsibility of the VirtualizerDelegate object to render elements for each layout info. The virtualizer manages a set of ReusableView objects, which are reused as the user scrolls by swapping their content with cached elements returned by the delegate.

Properties

Name	Type	Description
`delegate`	`VirtualizerDelegate<object, V>`	The virtualizer delegate. The delegate is used by the virtualizer to create and configure views.
`collection`	`Collection<object>`	The current content of the virtualizer.
`layout`	`Layout<object>`	The layout object that determines the visible views.
`contentSize`	`Size`	The size of the scrollable content.
`visibleRect`	`Rect`	The currently visible rectangle.
`persistedKeys`	`Set<Key>`	The set of persisted keys that are always present in the DOM, even if not currently in view.

Methods

Method	Description
`constructor( (options: VirtualizerOptions<object, V> )): void`
`isPersistedKey( (key: Key )): void`	Returns whether the given key, or an ancestor, is persisted.
`keyAtPoint( (point: Point )): Key \| null`	Returns the key for the item view currently at the given point.
`getVisibleLayoutInfos(): void`
`render( (opts: VirtualizerRenderOptions<object> )): ReusableView<object, V>[]`	Performs layout and updates visible views as needed.
`getVisibleView( (key: Key )): ReusableView<object, V> \| undefined`
`invalidate( (context: InvalidationContext )): void`
`updateItemSize( (key: Key, , size: Size )): void`

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.
`UNSTABLE_filter( (filterFn: ( (nodeValue: string )) => boolean )): Collection<T>`	Filters the collection using the given function.

Properties

Name	Type	Description
`width`	`number`
`height`	`number`
`area`	`any`	The total area of the Size.

Methods

Method	Description
`constructor( (width: any, , height: any )): void`
`copy(): Size`	Returns a copy of this size.
`equals( (other: Size )): boolean`	Returns whether this size is equal to another one.

Represents a rectangle.

Properties

Name	Type	Description
`x`	`number`	The x-coordinate of the rectangle.
`y`	`number`	The y-coordinate of the rectangle.
`width`	`number`	The width of the rectangle.
`height`	`number`	The height of the rectangle.
`maxX`	`number`	The maximum x-coordinate in the rectangle.
`maxY`	`number`	The maximum y-coordinate in the rectangle.
`area`	`number`	The area of the rectangle.
`topLeft`	`Point`	The top left corner of the rectangle.
`topRight`	`Point`	The top right corner of the rectangle.
`bottomLeft`	`Point`	The bottom left corner of the rectangle.
`bottomRight`	`Point`	The bottom right corner of the rectangle.

Methods

Method	Description
`constructor( x: any, y: any, width: any, height: any ): void`
`intersects( (rect: Rect )): boolean`	Returns whether this rectangle intersects another rectangle.
`containsRect( (rect: Rect )): boolean`	Returns whether this rectangle fully contains another rectangle.
`containsPoint( (point: Point )): boolean`	Returns whether the rectangle contains the given point.
`getCornerInRect( (rect: Rect )): RectCorner \| null`	Returns the first corner of this rectangle (from top to bottom, left to right) that is contained in the given rectangle, or null of the rectangles do not intersect.
`equals( (rect: Rect )): void`
`pointEquals( (point: Point \| \| Rect )): void`
`sizeEquals( (size: Size \| \| Rect )): void`
`union( (other: Rect )): void`	Returns the union of this Rect and another.
`intersection( (other: Rect )): Rect`	Returns the intersection of this Rect with another. If the rectangles do not intersect, an all zero Rect is returned.
`copy(): Rect`	Returns a copy of this rectangle.

Properties

Name	Type	Description
`x`	`number`	The x-coordinate of the point.
`y`	`number`	The y-coordinate of the point.

Methods

Method	Description
`constructor( (x: any, , y: any )): void`
`copy(): Point`	Returns a copy of this point.
`equals( (point: Point )): boolean`	Checks if two points are equal.
`isOrigin(): boolean`	Returns true if this point is the origin.

'topLeft'
  | 'topRight'
  | 'bottomLeft'
  | 'bottomRight'

Extends:

Properties

Name	Type	Description
`parent`	`ReusableView<object, V>`

Methods

Method	Description
`constructor( virtualizer: Virtualizer<object, V>, parent: ReusableView<object, V>, viewType: string ): void`

Virtualizer creates instances of the ReusableView class to represent views currently being displayed.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, V>`	The Virtualizer this view is a part of.
`layoutInfo`	`LayoutInfo \| null`	The LayoutInfo this view is currently representing.
`content`	`object \| null`	The content currently being displayed by this view, set by the virtualizer.
`rendered`	`V \| null`
`viewType`	`string`
`key`	`Key`
`children`	`Set<ChildView<object, V>>`
`reusableViews`	`Map<string, ChildView<object, V>[]>`

Methods

Method	Description
`constructor( (virtualizer: Virtualizer<object, V>, , viewType: string )): void`
`prepareForReuse(): void`	Prepares the view for reuse. Called just before the view is removed from the DOM.
`getReusableView( (reuseType: string )): void`
`reuseChild( (child: ChildView<object, V> )): void`

Instances of this lightweight class are created by Layout subclasses to represent each item in the Virtualizer. LayoutInfo objects describe various properties of an item, such as its position and size, and style information. The virtualizer uses this information when creating actual DOM elements to display.

Properties

Name	Type	Default	Description
`type`	`string`	—	The type of element represented by this LayoutInfo. Should match the `type` of the corresponding collection node.
`key`	`Key`	—	A unique key for this LayoutInfo. Should match the `key` of the corresponding collection node.
`parentKey`	`Key \| null`	—	The key for a parent LayoutInfo, if any.
`content`	`any \| null`	—	Content for this item if it was generated by the layout rather than coming from the Collection.
`rect`	`Rect`	—	The rectangle describing the size and position of this element.
`estimatedSize`	`boolean`	`false`	Whether the size is estimated. `false` by default. Items with estimated sizes will be measured the first time they are added to the DOM. The estimated size is used to calculate the size and position of the scrollbar.
`isSticky`	`boolean`	`false`	Whether the layout info sticks to the viewport when scrolling.
`opacity`	`number`	`1`	The element's opacity.
`transform`	`string \| null`	—	A CSS transform string to apply to the element. `null` by default.
`zIndex`	`number`	—	The z-index of the element. 0 by default.
`allowOverflow`	`boolean`	`false`	Whether the element allows its contents to overflow its container.

Methods

Method	Description
`constructor( type: string, key: Key, rect: Rect ): void`
`copy(): LayoutInfo`	Returns a copy of the LayoutInfo.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, V>`	The Virtualizer this view is a part of.
`layoutInfo`	`LayoutInfo \| null`	The LayoutInfo this view is currently representing.
`content`	`object \| null`	The content currently being displayed by this view, set by the virtualizer.
`rendered`	`V \| null`
`viewType`	`string`
`key`	`Key`
`children`	`Set<ChildView<object, V>>`
`reusableViews`	`Map<string, ChildView<object, V>[]>`

Methods

Method	Description
`constructor( (virtualizer: Virtualizer<object, V> )): void`
`prepareForReuse(): void`	Prepares the view for reuse. Called just before the view is removed from the DOM.
`getReusableView( (reuseType: string )): void`
`reuseChild( (child: ChildView<object, V> )): void`

Method	Description
`setVisibleRect( (rect: Rect )): void`
`getOverscannedRect(): void`

Name	Type	Description
`delegate`	`VirtualizerDelegate<object, V>`
`collection`	`Collection<object>`
`layout`	`Layout<object>`

Name	Type	Description
`type`	`'item'`	The drop target type.
`key`	`Key`	The item key.
`dropPosition`	`DropPosition`	The drop position relative to the item.

'on'
  | 'before'
  | 'after'

Virtualizer supports arbitrary layout objects, which compute what items are visible, and how to position and style them. However, layouts do not render items directly. Instead, layouts produce lightweight LayoutInfo objects which describe various properties of an item, such as its position and size. The Virtualizer is then responsible for creating the actual views as needed, based on this layout information.

Every layout extends from the Layout abstract base class. Layouts must implement the getVisibleLayoutInfos, getLayoutInfo, and getContentSize methods. All other methods can be optionally overridden to implement custom behavior.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, any> \| null`	The Virtualizer the layout is currently attached to.

Methods

Method	Description
`abstract getVisibleLayoutInfos( (rect: Rect )): LayoutInfo[]`	Returns an array of `LayoutInfo` objects which are inside the given rectangle. Should be implemented by subclasses.
`abstract getLayoutInfo( (key: Key )): LayoutInfo \| null`	Returns a `LayoutInfo` for the given key. Should be implemented by subclasses.
`abstract getContentSize(): Size`	Returns size of the content. By default, it returns virtualizer's size.
`shouldInvalidate( (newRect: Rect, , oldRect: Rect )): boolean`	Returns whether the layout should invalidate in response to visible rectangle changes. By default, it only invalidates when the virtualizer's size changes. Return true always to make the layout invalidate while scrolling (e.g. sticky headers).
`shouldInvalidateLayoutOptions( (newOptions: O, , oldOptions: O )): boolean`	Returns whether the layout should invalidate when the layout options change. By default it invalidates when the object identity changes. Override this method to optimize layout updates based on specific option changes.
`update( (invalidationContext: InvalidationContext<O> )): void`	This method allows the layout to perform any pre-computation it needs to in order to prepare LayoutInfos for retrieval. Called by the virtualizer before `getVisibleLayoutInfos` or `getLayoutInfo` are called.
`updateItemSize( (key: Key, , size: Size )): boolean`	Updates the size of the given item.
`getDropTargetLayoutInfo( (target: ItemDropTarget )): LayoutInfo`	Returns a `LayoutInfo` for the given drop target.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`index`	`number`	The index of this node within its parent.
`aria-label`	`string`	An accessibility label for this node.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

ListLayout is a virtualizer Layout implementation that arranges its items in a vertical stack. It supports both fixed and variable height items.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, any> \| null`	The Virtualizer the layout is currently attached to.

Methods

Method	Description
`constructor( (options: ListLayoutOptions )): void`	Creates a new ListLayout with options. See the list of properties below for a description of the options that can be provided.
`getLayoutInfo( (key: Key )): void`
`getVisibleLayoutInfos( (rect: Rect )): void`
`shouldInvalidateLayoutOptions( (newOptions: ListLayoutOptions, , oldOptions: ListLayoutOptions )): boolean`
`update( (invalidationContext: InvalidationContext<ListLayoutOptions> )): void`
`updateItemSize( (key: Key, , size: Size )): void`
`getContentSize(): void`
`getDropTargetFromPoint( x: number, y: number, isValidDropTarget: ( (target: DropTarget )) => boolean ): DropTarget \| null`
`getDropTargetLayoutInfo( (target: ItemDropTarget )): LayoutInfo`
`shouldInvalidate( (newRect: Rect, , oldRect: Rect )): boolean`	Returns whether the layout should invalidate in response to visible rectangle changes. By default, it only invalidates when the virtualizer's size changes. Return true always to make the layout invalidate while scrolling (e.g. sticky headers).

Name	Type	Description
`layoutInfo`	`LayoutInfo`
`validRect`	`Rect`
`node`	`Node<unknown>`
`children`	`LayoutNode[]`
`index`	`number`

Name	Type	Default	Description
`rowHeight`	`number`	`48`	The fixed height of a row in px.
`estimatedRowHeight`	`number`	—	The estimated height of a row, when row heights are variable.
`headingHeight`	`number`	`48`	The fixed height of a section header in px.
`estimatedHeadingHeight`	`number`	—	The estimated height of a section header, when the height is variable.
`loaderHeight`	`number`	`48`	The fixed height of a loader element in px. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections.
`dropIndicatorThickness`	`number`	`2`	The thickness of the drop indicator.
`gap`	`number`	`0`	The gap between items.
`padding`	`number`	`0`	The padding around the list.

Name	Type	Description
`contentChanged`	`boolean`
`offsetChanged`	`boolean`
`sizeChanged`	`boolean`
`itemSizeChanged`	`boolean`
`layoutOptionsChanged`	`boolean`
`layoutOptions`	`O`

RootDropTarget | ItemDropTarget

Name	Type	Description
`type`	`'root'`	The event type.

GridLayout is a virtualizer Layout implementation that arranges its items in a grid. The items are sized between a minimum and maximum size depending on the width of the container.

Properties

Name	Type	Description
`virtualizer`	`Virtualizer<object, any> \| null`	The Virtualizer the layout is currently attached to.

Methods

Method	Description
`shouldInvalidateLayoutOptions( (newOptions: GridLayoutOptions, , oldOptions: GridLayoutOptions )): boolean`
`update( (invalidationContext: InvalidationContext<GridLayoutOptions> )): void`
`getLayoutInfo( (key: Key )): LayoutInfo`
`getContentSize(): Size`
`getVisibleLayoutInfos( (rect: Rect )): LayoutInfo[]`
`updateItemSize( (key: Key, , size: Size )): void`
`getDropTargetFromPoint( x: number, y: number, isValidDropTarget: ( (target: DropTarget )) => boolean ): DropTarget`
`getDropTargetLayoutInfo( (target: ItemDropTarget )): LayoutInfo`
`shouldInvalidate( (newRect: Rect, , oldRect: Rect )): boolean`	Returns whether the layout should invalidate in response to visible rectangle changes. By default, it only invalidates when the virtualizer's size changes. Return true always to make the layout invalidate while scrolling (e.g. sticky headers).

Name	Type	Default	Description
`minItemSize`	`Size`	`200 x 200`	The minimum item size.
`maxItemSize`	`Size`	`Infinity`	The maximum item size.
`preserveAspectRatio`	`boolean`	`false`	Whether to preserve the aspect ratio of the `minItemSize`. By default, grid rows may have variable heights. When `preserveAspectRatio` is true, all rows will have equal heights.
`minSpace`	`Size`	`18 x 18`	The minimum space required between items.
`maxColumns`	`number`	`Infinity`	The maximum number of columns.
`dropIndicatorThickness`	`number`	`2`	The thickness of the drop indicator.

Extends: HTMLAttributes

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	The collection of items to render.
`persistedKeys`	`Set<Key> \| null`	A set of keys for items that should always be persisted in the DOM.
`scrollRef`	`RefObject<HTMLElement \| null>`	A ref to the scroll container for the collection.
`renderDropIndicator`	`( (target: ItemDropTarget )) => ReactNode`	A function that renders a drop indicator between items.

Name	Type	Description
`collection`	`Collection<Node<unknown>>`	The collection of items to render.
`parent`	`Node<unknown>`	The parent node of the items to render.
`renderDropIndicator`	`( (target: ItemDropTarget )) => ReactNode`	A function that renders a drop indicator between items.

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

Method	Description
`getDropTargetFromPoint( x: number, y: number, isValidDropTarget: ( (target: DropTarget )) => boolean ): DropTarget \| null`	Returns a drop target within a collection for the given x and y coordinates. The point is provided relative to the top left corner of the collection container. A drop target can be checked to see if it is valid using the provided `isValidDropTarget` function.