Skip to content

VirtualList

Use VirtualList for lists too long to render at once, thousands of rows or more, such as a chat history, a log or a feed, especially when the rows have different heights. For a few hundred rows or fewer, a plain list in a ScrollArea is simpler; to split a list into pages instead, use Pagination.

Before you start
  • The list is its own scroll container and takes height: 100% (and an inherited max-height) from its parent, so put it in a container with a height or a max-height.
  • Spread the style each row receives on the row’s root element and, with itemResizable, put its domRef there too, so the row is measured.

VirtualList is a virtual list with variable row heights: only the rows in view are rendered, and each row is measured when it mounts.

Demos

Basic

Rows of different heights, unknown until they mount. Scroll to index and Scroll to key jump to a row; pick an align to put it at the top, in the middle or at the bottom of the view.

Jumping to a row: align

scrollTo({ key, align }) (or index) puts the row’s top at the view’s top ("start"), its middle in the middle ("center") or its bottom at the bottom ("end"), inside scrollMarginTop and scrollMarginBottom. With the default behavior: "instant" the row lands exactly, to the pixel, and nothing else is ever painted, even when the row and the rows around it have never been measured:

  • Before the browser paints, the list mounts the row and the rows that fill the view around it, measures them (synchronously, not waiting for the ResizeObserver), works out the exact scrollTop from where the row really is, and sets it. If that brings other rows into view, or a size changes (a row that grows in its own layout effect), it measures again, up to 10 times; it is usually done after two or three. Rows far from the target keep their estimated sizes: only the rows in view need to be exact.
  • For one frame after the jump, sizes reported by the ResizeObserver repeat it, as for the other instant jumps.
  • At the ends the position is clamped (the last row cannot reach the top).
  • With behavior: "smooth" the list scrolls once to the position worked out from what is known when the jump starts.

Without align, the jump goes to the row’s estimated offset: with debounce (the default) the list scrolls only as far as needed to show the row, otherwise the row’s top goes to the estimated offset. Centering a row used to take a scroll-adjusting task (submitScrollAdjustingTask) that moved it after each batch of measurements, so the first, estimated position was painted before the correction; align replaces that.

Row margins

Rows may use margins freely. They are laid out in normal block flow, so their margins collapse as your CSS says: between adjacent rows, and a child’s margins through a row that has no border or padding of its own, exactly as in a plain list. Before the browser paints, the list measures from the layout the space each row actually takes (from where the row starts to where the next one starts, collapsed margins included), and positions the rows by it. The first row’s top margin and the last row’s bottom margin are kept. Rows need no display: flow-root, gap or similar.

Random heights

Add rows at the start or the end, and change the height of the rows in view or of every row.

Keeping the top row when rows are added above

With keepAnchorOnItemsChange, the row at the top of the view stays where it is when items change: rows inserted or removed above it, such as older messages loaded at the start of a chat, do not move what is on screen. Click Load 20 older, scroll a little, then Remove 5 above or Remove the top row. Switch the prop off to compare: the scroll position is kept instead, so the rows jump down by the height of the new rows.

  • Off by default. Turn it on for lists whose code inserts or removes rows above the view.
  • At the very top too. When the list is scrolled to the top, the row that was first stays in place and the new rows are above it, out of view: loading older rows does not scroll you away from what you were reading. With paddingTop, the padding is only above the first row, so after a prepend the space it took shows the end of the newest row above.
  • If the top row is removed, the first row after it that is still there keeps its place. If every row from the top row onwards is removed, the scroll position is kept.
  • A jump wins. An instant scrollTo made just before the change (to an index, a key, the top or the bottom) is carried out instead.
  • Rows that new rows go below can be excluded with canAnchorItem: a row it rejects is passed over like a removed one. For a leading row (a header, a “start of history” boundary) above a prepend: keeping it in place would push down the rows being read.

The list always does two related things on its own, with or without the prop: when you scroll up and rows above the view are mounted and measured for the first time, the difference from itemEstimatedSize is scrolled away, so the rows in view do not jump; and when a mounted row that ends above the view changes size (an image loads, a reaction is added), the change is scrolled away too. A row the view’s top cuts through is not compensated: part of it is in view. That covers scrolling and resizing only. keepAnchorOnItemsChange covers changes of items; the two work together (the rows a prepend adds are measured, and compensated, when you scroll up to them).

Keeping selected rows

While text is selected, rows scrolled out of view stay mounted, so the selection and copying survive scrolling. Click Select text in row 2, then Scroll to row 1000.

Virtual on and off

With virtualization off every row is rendered, and the row at the top of the view stays in place.

With ScrollArea's scrollbar

The list hides the native scrollbar. To show ScrollArea’s overlay scrollbar over it, bind the list’s own scroller with useScrollAreaContainer: domRef takes containerProps.ref, className and style take the container’s, and <ScrollAreaGutters {...guttersProps} /> goes in through header, the scroller’s first child (see ScrollArea). The list still scrolls, measures and anchors itself.