Virtualizer

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.

install	`yarn add react-aria-components`
version	1.7.0
usage	`import {Virtualizer} from 'react-aria-components'`

View repository

GitHub

View package

NPM

Example#

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

let items = [];
for (let i = 0; i < 5000; i++) {
  items.push({ id: i, name: `Item ${i}` });
}

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        rowHeight: 32,
        padding: 4,
        gap: 4
      }}
    >
      <ListBox
        aria-label="Virtualized ListBox"
        selectionMode="multiple"
        items={items}
      >
        {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
      </ListBox>
    </Virtualizer>
  );
}

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

let items = [];
for (let i = 0; i < 5000; i++) {
  items.push({ id: i, name: `Item ${i}` });
}

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        rowHeight: 32,
        padding: 4,
        gap: 4
      }}
    >
      <ListBox
        aria-label="Virtualized ListBox"
        selectionMode="multiple"
        items={items}
      >
        {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
      </ListBox>
    </Virtualizer>
  );
}

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

let items = [];
for (
  let i = 0;
  i < 5000;
  i++
) {
  items.push({
    id: i,
    name: `Item ${i}`
  });
}

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        rowHeight: 32,
        padding: 4,
        gap: 4
      }}
    >
      <ListBox
        aria-label="Virtualized ListBox"
        selectionMode="multiple"
        items={items}
      >
        {(item) => (
          <ListBoxItem>
            {item.name}
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

Features#

Virtualized scrolling 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.

Integrated – Works with React Aria ListBox, GridList, Tree, and Table components. Integrated with React Aria's drag and drop, selection, and table column resizing implementations.
Custom layouts – Support for list, grid, waterfall, and table layouts out of the box, with fixed or variable size items. Create a Layout subclass to build your own custom layout.
Accessible – Persists the focused element in the DOM even when out of view, ensuring keyboard navigation always works. Adds ARIA attributes like aria-rowindex to give screen reader users context.

Anatomy#

Collection components such as ListBox, GridList, Tree, and Table can be virtualized by wrapping them in a <Virtualizer>, and providing a Layout object such as ListLayout or GridLayout. See below for examples of each layout.

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

<Virtualizer layout={ListLayout}>
  <ListBox>
    {/* ... */}
  </ListBox>
</Virtualizer>

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

<Virtualizer layout={ListLayout}>
  <ListBox>
    {/* ... */}
  </ListBox>
</Virtualizer>

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

<Virtualizer
  layout={ListLayout}
>
  <ListBox>
    {/* ... */}
  </ListBox>
</Virtualizer>

Virtualized components must have a defined size

This may be an explicit CSS width and height, or an implicit size (e.g. percentage or flex) bounded by an ancestor element. Without a bounded size, all items will be rendered to the DOM, negating the performance benefits of virtualized scrolling.

Layouts#

Virtualizer uses Layout objects to determine the position and size of each item, and provide the list of currently visible items. When using a Virtualizer, all items are positioned by the Layout, and CSS layout properties such as flexbox and grid do not apply.

ListLayout#

ListLayout supports layout of items in a vertical stack. Rows can be fixed or variable height. When using variable heights, set the estimatedRowHeight to a reasonable guess for how tall the rows will be on average. This allows the size of the scrollbar to be calculated. ListLayout supports the following options:

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.

This example shows a GridList with variable height rows due to text wrapping.

import {ListLayout, Virtualizer} from 'react-aria-components';
import {MyGridList, MyItem} from './GridList';

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        estimatedRowHeight: 75,
        gap: 4,
        padding: 4
      }}    >
      <MyGridList
        aria-label="Virtualized GridList"
        selectionMode="multiple"
        items={items}
      >
        {(item) => <MyItem>{item.name}</MyItem>}
      </MyGridList>
    </Virtualizer>
  );
}

import {
  ListLayout,
  Virtualizer
} from 'react-aria-components';
import {MyGridList, MyItem} from './GridList';

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        estimatedRowHeight: 75,
        gap: 4,
        padding: 4
      }}    >
      <MyGridList
        aria-label="Virtualized GridList"
        selectionMode="multiple"
        items={items}
      >
        {(item) => <MyItem>{item.name}</MyItem>}
      </MyGridList>
    </Virtualizer>
  );
}

import {
  ListLayout,
  Virtualizer
} from 'react-aria-components';
import {
  MyGridList,
  MyItem
} from './GridList';

function Example() {
  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{
        estimatedRowHeight:
          75,
        gap: 4,
        padding: 4
      }}    >
      <MyGridList
        aria-label="Virtualized GridList"
        selectionMode="multiple"
        items={items}
      >
        {(item) => (
          <MyItem>
            {item.name}
          </MyItem>
        )}
      </MyGridList>
    </Virtualizer>
  );
}

GridLayout#

GridLayout supports layout of items in an equal size grid. The items are sized between a minimum and maximum size depending on the width of the container. It supports the following options:

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.

Make sure to set layout="grid" on the ListBox or GridList component as well so that keyboard navigation behavior is correct.

import {GridLayout, Size, Text} from 'react-aria-components';

function Example() {
  return (
    <div className="resizable">
      <Virtualizer
        layout={GridLayout}
        layoutOptions={{
          minItemSize: new Size(100, 140),
          minSpace: new Size(8, 8)
        }}      >
        <ListBox
          layout="grid"          aria-label="Virtualized grid layout"
          selectionMode="multiple"
          items={albums}>
          {item => (
            <ListBoxItem textValue={item.title}>
              <img src={item.image} alt="" />
              <Text slot="label">{item.title}</Text>
              <Text slot="description">{item.artist}</Text>
            </ListBoxItem>
          )}
        </ListBox>
      </Virtualizer>
    </div>
  );
}

import {
  GridLayout,
  Size,
  Text
} from 'react-aria-components';

function Example() {
  return (
    <div className="resizable">
      <Virtualizer
        layout={GridLayout}
        layoutOptions={{
          minItemSize: new Size(100, 140),
          minSpace: new Size(8, 8)
        }}      >
        <ListBox
          layout="grid"          aria-label="Virtualized grid layout"
          selectionMode="multiple"
          items={albums}
        >
          {(item) => (
            <ListBoxItem textValue={item.title}>
              <img src={item.image} alt="" />
              <Text slot="label">{item.title}</Text>
              <Text slot="description">{item.artist}</Text>
            </ListBoxItem>
          )}
        </ListBox>
      </Virtualizer>
    </div>
  );
}

import {
  GridLayout,
  Size,
  Text
} from 'react-aria-components';

function Example() {
  return (
    <div className="resizable">
      <Virtualizer
        layout={GridLayout}
        layoutOptions={{
          minItemSize:
            new Size(
              100,
              140
            ),
          minSpace:
            new Size(
              8,
              8
            )
        }}      >
        <ListBox
          layout="grid"          aria-label="Virtualized grid layout"
          selectionMode="multiple"
          items={albums}
        >
          {(item) => (
            <ListBoxItem
              textValue={item
                .title}
            >
              <img
                src={item
                  .image}
                alt=""
              />
              <Text slot="label">
                {item
                  .title}
              </Text>
              <Text slot="description">
                {item
                  .artist}
              </Text>
            </ListBoxItem>
          )}
        </ListBox>
      </Virtualizer>
    </div>
  );
}

WaterfallLayout#

WaterfallLayout arranges variable height items in a column layout. The columns are sized between a minimum and maximum size depending on the width of the container. It supports the following options:

Name	Type	Default	Description
`minItemSize`	`Size`	`200 x 200`	The minimum item size.
`maxItemSize`	`Size`	`Infinity`	The maximum item size.
`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.

import {Size, Text, WaterfallLayout} from 'react-aria-components';

function Example() {
  return (
    <Virtualizer
      layout={WaterfallLayout}
      layoutOptions={{
        minItemSize: new Size(150, 150),
        minSpace: new Size(8, 8)
      }}    >
      <ListBox
        layout="grid"
        aria-label="Virtualized waterfall layout"
        selectionMode="multiple"
        items={images}
      >
        {(item) => (
          <ListBoxItem textValue={item.title}>
            <img
              src={item.image}
              alt=""
              style={{ aspectRatio: item.aspectRatio }}
            />
            <Text slot="label">{item.title}</Text>
            <Text slot="description">{item.user}</Text>
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

import {
  Size,
  Text,
  WaterfallLayout
} from 'react-aria-components';

function Example() {
  return (
    <Virtualizer
      layout={WaterfallLayout}
      layoutOptions={{
        minItemSize: new Size(150, 150),
        minSpace: new Size(8, 8)
      }}    >
      <ListBox
        layout="grid"
        aria-label="Virtualized waterfall layout"
        selectionMode="multiple"
        items={images}
      >
        {(item) => (
          <ListBoxItem textValue={item.title}>
            <img
              src={item.image}
              alt=""
              style={{ aspectRatio: item.aspectRatio }}
            />
            <Text slot="label">{item.title}</Text>
            <Text slot="description">{item.user}</Text>
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

import {
  Size,
  Text,
  WaterfallLayout
} from 'react-aria-components';

function Example() {
  return (
    <Virtualizer
      layout={WaterfallLayout}
      layoutOptions={{
        minItemSize:
          new Size(
            150,
            150
          ),
        minSpace:
          new Size(8, 8)
      }}    >
      <ListBox
        layout="grid"
        aria-label="Virtualized waterfall layout"
        selectionMode="multiple"
        items={images}
      >
        {(item) => (
          <ListBoxItem
            textValue={item
              .title}
          >
            <img
              src={item
                .image}
              alt=""
              style={{
                aspectRatio:
                  item
                    .aspectRatio
              }}
            />
            <Text slot="label">
              {item
                .title}
            </Text>
            <Text slot="description">
              {item.user}
            </Text>
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

TableLayout#

TableLayout provides layout of items in rows and columns, supporting virtualization of both horizontal and vertical scrolling. It should be used with the Table component. Rows can be fixed or variable height. When using variable heights, set the estimatedRowHeight to a reasonable guess for how tall the rows will be on average. This allows the size of the scrollbar to be calculated. TableLayout supports the following options:

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.

import {Cell, Column, Row, Table, TableBody, TableHeader, TableLayout} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let rows = [];
for (let i = 0; i < 1000; i++) {
  rows.push({ id: i, foo: `Foo ${i}`, bar: `Bar ${i}`, baz: `Baz ${i}` });
}

function Example() {
  return (
    <Virtualizer
      layout={TableLayout}
      layoutOptions={{
        rowHeight: 32,
        headingHeight: 32,
        padding: 4,
        gap: 4
      }}    >
      <Table aria-label="Virtualized Table" selectionMode="multiple">
        <TableHeader>
          <Column width={40} minWidth={0}>
            <MyCheckbox slot="selection" />
          </Column>
          <Column isRowHeader>Foo</Column>
          <Column>Bar</Column>
          <Column>Baz</Column>
        </TableHeader>
        <TableBody items={rows}>
          {(item) => (
            <Row style={{ width: 'inherit', height: 'inherit' }}>
              <Cell>
                <MyCheckbox slot="selection" />
              </Cell>
              <Cell>{item.foo}</Cell>
              <Cell>{item.bar}</Cell>
              <Cell>{item.baz}</Cell>
            </Row>
          )}
        </TableBody>
      </Table>
    </Virtualizer>
  );
}

import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
  TableLayout
} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let rows = [];
for (let i = 0; i < 1000; i++) {
  rows.push({
    id: i,
    foo: `Foo ${i}`,
    bar: `Bar ${i}`,
    baz: `Baz ${i}`
  });
}

function Example() {
  return (
    <Virtualizer
      layout={TableLayout}
      layoutOptions={{
        rowHeight: 32,
        headingHeight: 32,
        padding: 4,
        gap: 4
      }}    >
      <Table
        aria-label="Virtualized Table"
        selectionMode="multiple"
      >
        <TableHeader>
          <Column width={40} minWidth={0}>
            <MyCheckbox slot="selection" />
          </Column>
          <Column isRowHeader>Foo</Column>
          <Column>Bar</Column>
          <Column>Baz</Column>
        </TableHeader>
        <TableBody items={rows}>
          {(item) => (
            <Row
              style={{
                width: 'inherit',
                height: 'inherit'
              }}
            >
              <Cell>
                <MyCheckbox slot="selection" />
              </Cell>
              <Cell>{item.foo}</Cell>
              <Cell>{item.bar}</Cell>
              <Cell>{item.baz}</Cell>
            </Row>
          )}
        </TableBody>
      </Table>
    </Virtualizer>
  );
}

import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
  TableLayout
} from 'react-aria-components';
import {MyCheckbox} from './Checkbox';

let rows = [];
for (
  let i = 0;
  i < 1000;
  i++
) {
  rows.push({
    id: i,
    foo: `Foo ${i}`,
    bar: `Bar ${i}`,
    baz: `Baz ${i}`
  });
}

function Example() {
  return (
    <Virtualizer
      layout={TableLayout}
      layoutOptions={{
        rowHeight: 32,
        headingHeight:
          32,
        padding: 4,
        gap: 4
      }}    >
      <Table
        aria-label="Virtualized Table"
        selectionMode="multiple"
      >
        <TableHeader>
          <Column
            width={40}
            minWidth={0}
          >
            <MyCheckbox slot="selection" />
          </Column>
          <Column
            isRowHeader
          >
            Foo
          </Column>
          <Column>
            Bar
          </Column>
          <Column>
            Baz
          </Column>
        </TableHeader>
        <TableBody
          items={rows}
        >
          {(item) => (
            <Row
              style={{
                width:
                  'inherit',
                height:
                  'inherit'
              }}
            >
              <Cell>
                <MyCheckbox slot="selection" />
              </Cell>
              <Cell>
                {item
                  .foo}
              </Cell>
              <Cell>
                {item
                  .bar}
              </Cell>
              <Cell>
                {item
                  .baz}
              </Cell>
            </Row>
          )}
        </TableBody>
      </Table>
    </Virtualizer>
  );
}

Advanced: Custom layouts#

Custom Virtualizer layouts can be created by extending the Layout abstract base class. At a minimum, the getVisibleLayoutInfos, getLayoutInfo, and getContentSize methods must be implemented. You can override the other methods to customize their default behavior.

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.

LayoutInfo#

Layouts produce LayoutInfo objects describing the position, size, and other properties of each item in a collection. Virtualizer requests this information when needed, and uses it to create DOM nodes to display.

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.

Example#

This example implements a horizontally scrolling layout with fixed size items.

import {Key, Layout, LayoutInfo, Rect, Size} from 'react-aria-components';

class HorizontalLayout extends Layout {
  // Determine which items are visible within the given rectangle.
  getVisibleLayoutInfos(rect: Rect): LayoutInfo[] {
    let virtualizer = this.virtualizer!;
    let keys = Array.from(virtualizer.collection.getKeys());
    let startIndex = Math.max(0, Math.floor(rect.x / 100));
    let endIndex = Math.min(keys.length - 1, Math.ceil(rect.maxX / 100));
    let layoutInfos = [];
    for (let i = startIndex; i <= endIndex; i++) {
      layoutInfos.push(this.getLayoutInfo(keys[i]));
    }

    // Always add persisted keys (e.g. the focused item), even when out of view.
    for (let key of virtualizer.persistedKeys) {
      let item = virtualizer.collection.getItem(key);
      if (item?.index < startIndex) {
        layoutInfos.unshift(this.getLayoutInfo(key));
      } else if (item?.index > endIndex) {
        layoutInfos.push(this.getLayoutInfo(key));
      }
    }

    return layoutInfos;
  }

  // Provide a LayoutInfo for a specific item.
  getLayoutInfo(key: Key): LayoutInfo | null {
    let node = this.virtualizer!.collection.getItem(key);
    if (!node) {
      return null;
    }

    let rect = new Rect(node.index * 100, 0, 100, 100);
    return new LayoutInfo(node.type, node.key, rect);
  }

  // Provide the total size of all items.
  getContentSize(): Size {
    let numItems = this.virtualizer!.collection.size;
    return new Size(numItems * 100, 100);
  }
}

function Example() {
  let items = [];
  for (let i = 0; i < 200; i++) {
    items.push({ id: i, name: `Item ${i}` });
  }

  return (
    <Virtualizer layout={HorizontalLayout}>
      <ListBox
        aria-label="Favorite animal"
        items={items}
        orientation="horizontal"
        style={{ height: 'fit-content' }}
      >
        {(item) => <ListBoxItem className="item">{item.name}</ListBoxItem>}
      </ListBox>
    </Virtualizer>
  );
}

import {
  Key,
  Layout,
  LayoutInfo,
  Rect,
  Size
} from 'react-aria-components';

class HorizontalLayout extends Layout {
  // Determine which items are visible within the given rectangle.
  getVisibleLayoutInfos(rect: Rect): LayoutInfo[] {
    let virtualizer = this.virtualizer!;
    let keys = Array.from(virtualizer.collection.getKeys());
    let startIndex = Math.max(0, Math.floor(rect.x / 100));
    let endIndex = Math.min(
      keys.length - 1,
      Math.ceil(rect.maxX / 100)
    );
    let layoutInfos = [];
    for (let i = startIndex; i <= endIndex; i++) {
      layoutInfos.push(this.getLayoutInfo(keys[i]));
    }

    // Always add persisted keys (e.g. the focused item), even when out of view.
    for (let key of virtualizer.persistedKeys) {
      let item = virtualizer.collection.getItem(key);
      if (item?.index < startIndex) {
        layoutInfos.unshift(this.getLayoutInfo(key));
      } else if (item?.index > endIndex) {
        layoutInfos.push(this.getLayoutInfo(key));
      }
    }

    return layoutInfos;
  }

  // Provide a LayoutInfo for a specific item.
  getLayoutInfo(key: Key): LayoutInfo | null {
    let node = this.virtualizer!.collection.getItem(key);
    if (!node) {
      return null;
    }

    let rect = new Rect(node.index * 100, 0, 100, 100);
    return new LayoutInfo(node.type, node.key, rect);
  }

  // Provide the total size of all items.
  getContentSize(): Size {
    let numItems = this.virtualizer!.collection.size;
    return new Size(numItems * 100, 100);
  }
}

function Example() {
  let items = [];
  for (let i = 0; i < 200; i++) {
    items.push({ id: i, name: `Item ${i}` });
  }

  return (
    <Virtualizer layout={HorizontalLayout}>
      <ListBox
        aria-label="Favorite animal"
        items={items}
        orientation="horizontal"
        style={{ height: 'fit-content' }}
      >
        {(item) => (
          <ListBoxItem className="item">
            {item.name}
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

import {
  Key,
  Layout,
  LayoutInfo,
  Rect,
  Size
} from 'react-aria-components';

class HorizontalLayout
  extends Layout {
  // Determine which items are visible within the given rectangle.
  getVisibleLayoutInfos(
    rect: Rect
  ): LayoutInfo[] {
    let virtualizer =
      this.virtualizer!;
    let keys = Array
      .from(
        virtualizer
          .collection
          .getKeys()
      );
    let startIndex = Math
      .max(
        0,
        Math.floor(
          rect.x / 100
        )
      );
    let endIndex = Math
      .min(
        keys.length - 1,
        Math.ceil(
          rect.maxX / 100
        )
      );
    let layoutInfos = [];
    for (
      let i = startIndex;
      i <= endIndex;
      i++
    ) {
      layoutInfos.push(
        this
          .getLayoutInfo(
            keys[i]
          )
      );
    }

    // Always add persisted keys (e.g. the focused item), even when out of view.
    for (
      let key
        of virtualizer
          .persistedKeys
    ) {
      let item =
        virtualizer
          .collection
          .getItem(key);
      if (
        item?.index <
          startIndex
      ) {
        layoutInfos
          .unshift(
            this
              .getLayoutInfo(
                key
              )
          );
      } else if (
        item?.index >
          endIndex
      ) {
        layoutInfos.push(
          this
            .getLayoutInfo(
              key
            )
        );
      }
    }

    return layoutInfos;
  }

  // Provide a LayoutInfo for a specific item.
  getLayoutInfo(
    key: Key
  ): LayoutInfo | null {
    let node = this
      .virtualizer!
      .collection
      .getItem(key);
    if (!node) {
      return null;
    }

    let rect = new Rect(
      node.index * 100,
      0,
      100,
      100
    );
    return new LayoutInfo(
      node.type,
      node.key,
      rect
    );
  }

  // Provide the total size of all items.
  getContentSize(): Size {
    let numItems =
      this.virtualizer!
        .collection.size;
    return new Size(
      numItems * 100,
      100
    );
  }
}

function Example() {
  let items = [];
  for (
    let i = 0;
    i < 200;
    i++
  ) {
    items.push({
      id: i,
      name: `Item ${i}`
    });
  }

  return (
    <Virtualizer
      layout={HorizontalLayout}
    >
      <ListBox
        aria-label="Favorite animal"
        items={items}
        orientation="horizontal"
        style={{
          height:
            'fit-content'
        }}
      >
        {(item) => (
          <ListBoxItem className="item">
            {item.name}
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  );
}

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.

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'

string | number

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'

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.

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`

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.