React Aria
DocsReleasesBlog
React Aria

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.

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

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

<Virtualizer
  layout={ListLayout}
  layoutOptions={{rowSize: 32, gap: 4, padding: 4}}
>
  <ListBox
    aria-label="Virtualized ListBox"
    selectionMode="multiple"
    items={items}
    style={{display: 'block', padding: 0}}>
    {item => <ListBoxItem style={{height: '100%', minHeight: 0}}>{item.name}</ListBoxItem>}
  </ListBox>
</Virtualizer>

Layouts

Virtualizer uses 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.

List

ListLayout places items along its orientation. Rows can be fixed or variable in size. When using a variable size, set the estimatedRowSize to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.

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

let lorem = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sit amet tristique risus. In sit amet suscipit lorem. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. In condimentum imperdiet metus non condimentum. Duis eu velit et quam accumsan tempus at id velit. Duis elementum elementum purus, id tempus mauris posuere a. Nunc vestibulum sapien pellentesque lectus commodo ornare.'.split(' ');
let items: {id: number, name: string}[] = [];
for (let i = 0; i < 5000; i++) {
  let words = Math.max(2, Math.floor(Math.random() * 25));
  let name = lorem.slice(0, words).join(' ');
  items.push({id: i, name});
}

<Virtualizer
  layout={ListLayout}
  layoutOptions={{estimatedRowSize: 75, gap: 4, padding: 4}}
>
  <ListBox
    aria-label="Virtualized ListBox"
    selectionMode="multiple"
    items={items}
    style={{display: 'block', padding: 0}}>
    {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
  </ListBox>
</Virtualizer>

Use the orientation option to arrange items horizontally or vertically. Provide the same orientation on the collection component so keyboard navigation matches the layout.

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



for (let i = 0; imageOptions.length < 500; i++) {
  imageOptions.push({...imageOptions[i % 30], id: String(i)});
}

<Virtualizer
  layout={ListLayout}
  layoutOptions={{
    estimatedRowSize: 100, 
    gap: 8, 
    padding: 8, 
    orientation: "horizontal"
  }}
>
  <ListBox
    orientation="horizontal"
    aria-label="Horizontal virtualized list"
    selectionMode="multiple"
    items={imageOptions}
    style={{display: 'block', padding: 0, height: 250}}>
    {(item) => (
      <ListBoxItem textValue={item.title} aria-label={item.title} style={{width: Math.round(200 * Number(item.aspectRatio) + 24), height: '100%', padding: 12, overflow: 'hidden', boxSizing: 'border-box', border: '2px solid var(--border-color)', borderRadius: 8}}>
        <img src={item.image} alt="" style={{maxHeight: 200, aspectRatio: item.aspectRatio, borderRadius: 4}} />
      </ListBoxItem>
    )}
  </ListBox>
</Virtualizer>

Grid

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. Make sure to set layout="grid" on the ListBox or GridList component as well so that keyboard navigation behavior is correct.

minItemSize 
maxItemSize 
minSpace 
 
preserveAspectRatio 
import {Virtualizer, GridLayout} from 'react-aria-components/Virtualizer';
import {GridList, GridListItem, Text} from './GridList';



type Album = {id: number, image: string, title: string, artist: string};
let albums: Album[] = [];
for (let i = 0; i < 1000; i++) {
  albums.push({
    id: i,
    ...albumOptions[i % albumOptions.length]
  })
}

function Example(props) {
  return (
    <div className="resizable">
      <Virtualizer
        layout={GridLayout}
        layoutOptions={{
          minItemSize: new Size(100, 140), 
          minSpace: new Size(8, 8), 
          maxColumns: Infinity, 
          preserveAspectRatio: false
        }}
        {...props}>
        <GridList
          layout="grid"
          aria-label="Virtualized grid layout"
          selectionMode="multiple"
          items={albums}
          data-size="small"
          style={{display: 'block', padding: 0, height: 300, width: '100%'}}>
          {item => (
            <GridListItem textValue={item.title} style={{height: '100%'}}>
              <img src={item.image} alt="" />
              <Text>{item.title}</Text>
              <Text slot="description">{item.artist}</Text>
            </GridListItem>
          )}
        </GridList>
      </Virtualizer>
    </div>
  );
}

Waterfall

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.

minItemSize 
maxItemSize 
minSpace 
 
import {Virtualizer, WaterfallLayout} from 'react-aria-components/Virtualizer';
import {GridList, GridListItem, Text} from './GridList';



for (let i = 0; images.length < 500; i++) {
  images.push({...images[i % 30], id: String(i)});
}

<Virtualizer
  layout={WaterfallLayout}
  layoutOptions={{
    minItemSize: new Size(150, 150), 
    minSpace: new Size(8, 8), 
    maxColumns: Infinity
  }}
>
  <GridList
    layout="grid"
    aria-label="Virtualized waterfall layout"
    selectionMode="multiple"
    items={images}
    data-size="small"
    style={{display: 'block', padding: 0, height: 400, width: '100%'}}>
    {item => (
      <GridListItem textValue={item.title}>
        <img src={item.image} alt="" style={{aspectRatio: item.aspectRatio, maxWidth: 'none'}} />
        <Text>{item.title}</Text>
        <Text slot="description">{item.user}</Text>
      </GridListItem>
    )}
  </GridList>
</Virtualizer>

Table

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.

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

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

<Virtualizer
  layout={TableLayout}
  layoutOptions={{
    rowHeight: 32, 
    headingHeight: 32, 
    padding: 4, 
    gap: 4
  }}
>
  <Table
    aria-label="Virtualized Table"
    selectionMode="multiple"
    style={{
      width: '100%',
      height: 300,
      overflow: 'auto',
      scrollPaddingTop: 38
    }}>
    <TableHeader
      style={{
        background: 'var(--gray-100)',
        width: '100%',
        height: '100%',
        borderRadius: 8,
        fontWeight: 'bold'
      }}>
      <Column isRowHeader>Foo</Column>
      <Column>Bar</Column>
      <Column>Baz</Column>
    </TableHeader>
    <TableBody items={rows}>
      {(item) => (
        <Row style={{width: 'inherit', height: 'inherit'}}>
          <Cell>{item.foo}</Cell>
          <Cell>{item.bar}</Cell>
          <Cell>{item.baz}</Cell>
        </Row>
      )}
    </TableBody>
  </Table>
</Virtualizer>

Dynamic item sizes

Use the shouldObserveItemSize prop to automatically re-layout when items change size. Note that this uses a ResizeObserver internally and may have performance overhead.

import {Virtualizer, ListLayout} from 'react-aria-components/Virtualizer';
import {GridList, GridListItem, Text} from './GridList';
import {Button} from './Button';
import {useState} from 'react';
import {ChevronRight, ChevronDown} from 'lucide-react';

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

function ExpandableItem({item}) {
  let [expanded, setExpanded] = useState(false);
  return (
    <div className="expandable-item">
      <Text>{item.name}</Text>
      <Button
        variant="quiet"
        onPress={() => setExpanded(!expanded)} 
        aria-label={expanded ? 'Collapse' : 'Expand'}>
        {expanded ? <ChevronDown size={18} /> : <ChevronRight size={18} />}
      </Button>
      <Text slot="description" style={{display: expanded ? 'block' : 'none'}}>This is an expanded item.</Text>
    </div>
  );
}

<Virtualizer
  layout={ListLayout}
  layoutOptions={{
    estimatedRowHeight: 25,
    gap: 4,
  }}
  shouldObserveItemSize>
  <GridList
    style={{display: 'block', padding: 4, height: 400, width: '100%'}}
    aria-label="virtualized with expandable rows"
    items={items}>
    {item =>
    <GridListItem textValue={item.name} style={{padding: 0}}><ExpandableItem item={item} /></GridListItem>}
  </GridList>
</Virtualizer>

Examples

API

Virtualizer

NameType
childrenReactNode

The child collection to virtualize (e.g. ListBox, GridList, or Table).

layout<O> | <O>

The layout object that determines the position and size of the visible elements.

layoutOptionsO

Options for the layout.

shouldObserveItemSizeboolean

Whether to observe each item's size with a ResizeObserver and re-measure when it changes.

ListLayout

NameTypeDefault
orientationDefault: 'vertical'

The primary orientation of the items. Usually this is the direction that the collection scrolls.

rowSizenumberDefault: 48

The fixed size of a row in px with respect to the applied orientation.

estimatedRowSizenumberDefault: —

The estimated size of a row in px with respect to the applied orientation, when row sizes are variable.

headingSizenumberDefault: 48

The fixed size of a section header in px with respect to the applied orientation.

estimatedHeadingSizenumberDefault: —

The estimated size of a section header in px with respect to the applied orientation, when heading sizes are variable.

loaderSizenumberDefault: 48

The fixed size of a loader element in px with respect to the applied orientation. This loader is specifically for "load more" elements rendered when loading more rows at the root level or inside nested row/sections.

dropIndicatorThicknessnumberDefault: 2

The thickness of the drop indicator.

gapnumberDefault: 0

The gap between items.

paddingnumberDefault: 0

The padding around the list.

GridLayout

NameTypeDefault
minItemSizeDefault: 200 x 200

The minimum item size.

maxItemSizeDefault: Infinity

The maximum item size.

preserveAspectRatiobooleanDefault: 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.

minSpaceDefault: 18 x 18

The minimum space required between items.

maxHorizontalSpacenumberDefault: Infinity

The maximum allowed horizontal space between items.

maxColumnsnumberDefault: Infinity

The maximum number of columns.

dropIndicatorThicknessnumberDefault: 2

The thickness of the drop indicator.

loaderHeightnumberDefault: 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.

WaterfallLayout

NameTypeDefault
minItemSizeDefault: 200 x 200

The minimum item size.

maxItemSizeDefault: Infinity

The maximum item size.

minSpaceDefault: 18 x 18

The minimum space required between items.

maxHorizontalSpacenumberDefault: Infinity

The maximum allowed horizontal space between items.

maxColumnsnumberDefault: Infinity

The maximum number of columns.

dropIndicatorThicknessnumberDefault: 2

The thickness of the drop indicator.

loaderHeightnumberDefault: 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.

TableLayout

NameTypeDefault
rowHeightnumberDefault: 48

The fixed height of a row in px.

estimatedRowHeightnumberDefault: —

The estimated height of a row, when row heights are variable.

headingHeightnumberDefault: 48

The fixed height of a section header in px.

estimatedHeadingHeightnumberDefault: —

The estimated height of a section header, when the height is variable.

loaderHeightnumberDefault: 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.

columnWidthsMap<Key, number>Default: —
dropIndicatorThicknessnumberDefault: 2

The thickness of the drop indicator.

gapnumberDefault: 0

The gap between items.

paddingnumberDefault: 0

The padding around the list.