Skip to content

List virtualization

Render the rows that fit in the scroll area plus a few beyond its edges, and keep the scrollbar honest with a spacer sized for the whole list. It's how a long list stays cheap to scroll.

On this page

What it is

A list virtualizer leaves the item data where it was and decides which rows get DOM nodes: those in or near the viewport. The usual shape: a scroll container with a fixed height, a virtualizer that knows the item count, a size per row and an overscan, a render step that draws the virtual items it returns, and a spacer or padding that keeps the total scroll height equal to what the full list would take. The TanStack virtualized table guide describes most table implementations as following this pattern.

With rows of one fixed height the arithmetic is cheap. The first visible index is the scroll offset divided by the row height, rounded down; the last is the offset plus the container height, divided the same way, rounded up, minus one. Each rendered row is positioned at its index times the row height inside a relative container whose height is the count times the row height, so the browser's scrollbar reflects the whole list while the DOM holds just the rows in range. When a scroll moves the range across a row boundary, the rows that left it are dropped (or recycled) and the rows that entered it are drawn.

ts
const ROW = 40;      // px, all rows share this height
const OVERSCAN = 3;  // rows drawn past each edge

function visibleRange(scrollTop: number, boxHeight: number, count: number) {
  const first = Math.floor(scrollTop / ROW);
  const last = Math.ceil((scrollTop + boxHeight) / ROW) - 1;
  return {
    start: Math.max(0, first - OVERSCAN),
    end: Math.min(count - 1, last + OVERSCAN),
  };
}

function renderList(items: Item[], scrollTop: number, boxHeight: number) {
  const { start, end } = visibleRange(scrollTop, boxHeight, items.length);
  const rows = [];
  for (let i = start; i <= end; i++) {
    rows.push(
      <Row key={items[i].id} item={items[i]}
           style={{ position: 'absolute', top: i * ROW, height: ROW }} />
    );
  }
  // the spacer gives the scrollbar the height of the whole list
  return <div style={{ position: 'relative', height: items.length * ROW }}>{rows}</div>;
}

Overscan is the number of rows drawn beyond the visible edges. Rows in a virtualized list change when the person scrolls, so a fast scroll can briefly show empty space where the next rows haven't mounted yet. react-window exposes this as the overscanCount prop, described in its List types as a way to reduce flicker near the edges; the web.dev guide to the library gives its default as 1 and warns that a few more rows reduce the flash while a large overscan gives back the savings you came for.

Variable heights break the arithmetic because an index no longer maps to an offset. The virtualizer takes an estimated size as its first guess, lays the rows out from that, then measures each row once it has rendered and corrects the offsets that follow. The same library's List types, on its main branch, warn that dynamic row heights are less efficient than heights known ahead of time, which is why a uniform row is worth designing for when you can.

Keys matter because rows enter and leave the rendered range as the person scrolls. That library keys rows by index by default and offers a rowKey prop; a stable key from the item itself helps when the list can be sorted or filtered and the row holds state such as an expanded panel.

When to use it

Reach for it when a single list can grow long enough that the DOM cost per row shows up in scrolling: a chat history, a log viewer, a data table, a feed, or a result list with no natural page break. The official virtualized table examples are built around generated datasets of tens or hundreds of thousands of rows, the scale the pattern is built for.

Combine it with lazy loading when the data is also large on the server. One documented pattern wraps the list in an infinite loader that takes isItemLoaded, itemCount (the number you have or expect) and loadMoreItems, a callback that returns a promise for the next batch, so rows are fetched as scrolling approaches them. Pagination and infinite scroll covers the fetching side.

Give assistive technology the count it can no longer see. Browsers count list items from the DOM, so a screen reader on a virtualized list would report the handful of rendered rows as the whole set. aria-setsize states the real number of items when not all of them are in the DOM, aria-posinset gives each rendered row its position from 1 to that number, and a value of -1 says the size is unknown, which is the right choice for a feed whose length is indefinite or changes often. react-window's List, on its main branch, hands each row an ariaAttributes object holding aria-posinset, aria-setsize and a listitem role to spread onto its element for this.

Pick the library shape that fits the component you're designing. TanStack Virtual is headless: it computes the range and offsets but renders no markup or styles, and can run vertically, horizontally or both for a grid. A component library such as react-window instead ships a List that takes a rowComponent, a rowCount and a rowHeight. For a shared box that several teams skin differently, the headless shape lets each team pass its own row renderer while the box owns scrolling, keyboard focus and the visible range; see Designing a component API.

When not to

Don't virtualize a short list. A small dropdown or a settings page of simple rows usually renders fine as plain DOM, and virtualization adds scroll tracking, a positioning scheme, a measurement step for uneven rows and the accessibility work above. Our advice: profile first, and reach for it once the profile shows the rows themselves, by their count or by their cost, are what makes scrolling slow.

When the content is already in the HTML and the goal is a faster first load, try content-visibility: auto before any JavaScript. The browser skips layout and paint for an element with that value until it approaches the viewport, while the off-screen content stays in the DOM and the accessibility tree, so find-in-page and screen readers still reach it. Because the skipped element is laid out as if empty, pair it with contain-intrinsic-size so it keeps a placeholder height and the scrollbar doesn't jump. The property reached Baseline Newly available in September 2024.

Weigh what rows outside the DOM cost you. Text that hasn't been rendered has nothing for the browser's find-in-page to match and nothing for a crawler to index, where a content-visibility page keeps that text searchable. If people rely on find-in-page over a long document, or the rows are the content you want indexed, a paginated page or the CSS route serves them better.

Compared

ApproachWhat it doesReach for it whenWhat it costs

Render everything

One DOM node per row, plain scrolling

The list stays short and the rows are cheap to render

DOM size grows with the data; the cost shows as rows become many or heavy

content-visibility: auto

Browser skips layout and paint of off-screen elements that stay in the DOM

Content is already in the HTML and must stay searchable and accessible

Usually paired with contain-intrinsic-size so skipped elements keep a placeholder height; all nodes still exist

Fixed-height virtualization

Computes the visible range by arithmetic and renders those rows plus overscan

Rows share one height, or you can design them to

Constrains the row design; off-screen text is absent from the page

Variable-height virtualization

Lays out from an estimate, then measures rendered rows and corrects offsets

Rows wrap or expand and the list is long

More complex and less efficient than known heights; scroll position can shift as measurements land

Pagination or infinite loading

Limits how much data is fetched at once

The data lives on the server and the person rarely needs all of it

Classic pagination swaps one page's DOM for the next; an accumulating infinite scroll grows the DOM unless paired with virtualization

In a picture

Scroll box 400 pxtall

Step 1 of 4

A fixed-height scroll box

The list has 10,000 items in memory and rows of 40 px. The scroll box is 400 px tall, so ten rows fit at a time.

How to say it in an interview

The common mistake

Quiz

A virtualized list renders 16 rows but wraps them in an empty container that is 400,000 px tall. What is the container for?
During a fast scroll people see a white gap before the next rows appear. Which change addresses it directly?
A screen reader announces 'item 3 of 16' in a list of 10,000. What fixes the count?
A long article page with all of its HTML already delivered is slow to render on first load, and find-in-page must keep working. What fits best?

Questions that use this

Hear it in

Related

Sources

  1. TanStack Table: Virtualization guide
  2. TanStack Virtual: Introduction
  3. react-window: List prop types (lib/components/list/types.ts, main branch)
  4. web.dev: Virtualize large lists with react-window
  5. MDN: content-visibility
  6. web.dev: content-visibility, the CSS property that boosts rendering performance
  7. web.dev: The CSS content-visibility property is now Baseline Newly available
  8. MDN: aria-setsize
  9. MDN: ARIA feed role
Sign in to report a mistake