Virtual Lists (Windowing) — React Deep Dive

the windowing idea: O(viewport), not O(data)

A plain items.map() mounts one DOM node per item — 1,000 rows → 1,000 nodes, and the browser re-layouts all of them on every scroll. Virtualization renders only the slice inside the scroll viewport. The scrollbar is faked with a full-height spacer (height = total × itemHeight); the visible rows are absolutely positioned inside it. As you scroll, onScroll → setScrollTop recomputes the slice and React mounts/unmounts just the rows entering or leaving the window.

variable	formula	example (scrollTop = 1200px)
`startIndex`	`floor(scrollTop / itemHeight)`	floor(1200 / 40) = 30
`visibleCount`	`ceil(viewportHeight / itemHeight) + overscan`	ceil(400 / 40) + 2 = 12
`endIndex`	`min(startIndex + visibleCount, total)`	min(30 + 12, 10000) = 42
`offsetY` (spacer)	`startIndex × itemHeight` (= the inner div's full height sells the scrollbar)	30 × 40 = 1200px
`row top`	`i × itemHeight` (absolute position inside spacer)	row #35 → top = 1400px

1 · the virtual list you write (edit me)

var TOTAL = 1000;
var ITEM_HEIGHT = 36;
var VIEWPORT_HEIGHT = 288; // 8 rows visible (288 / 36)

function VirtualList() {
  var [scrollTop, setScrollTop] = React.useState(0);

  // --- the windowing math (recomputed on every scroll) ---
  var startIndex = Math.floor(scrollTop / ITEM_HEIGHT);
  var visibleCount = Math.ceil(VIEWPORT_HEIGHT / ITEM_HEIGHT) + 2; // +2 overscan buffer
  var endIndex = Math.min(startIndex + visibleCount, TOTAL);
  var renderedCount = endIndex - startIndex;

  // --- build ONLY the visible slice (never all 1000) ---
  var items = [];
  for (var i = startIndex; i < endIndex; i++) {
    items.push(
      <div
        key={i}
        data-testid={"item-" + i}
        className="flex items-center px-4 text-sm text-[#e6edf3] border-b border-[#30363d] bg-[#0d1117]"
        style={{
          height: ITEM_HEIGHT + "px",
          position: "absolute",
          top: i * ITEM_HEIGHT + "px",
          left: 0,
          right: 0
        }}
      >
        Item #{i + 1} of {TOTAL}
      </div>
    );
  }

  return (
    <div className="max-w-md mx-auto p-4 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-base font-bold text-[#61dafb] mb-3">
        Virtual List ({TOTAL.toLocaleString()} rows)
      </h2>

      <div
        data-testid="viewport"
        onScroll={function (e) { setScrollTop(e.target.scrollTop); }}
        style={{
          height: VIEWPORT_HEIGHT + "px",
          overflowY: "auto",
          position: "relative",
          border: "1px solid #30363d",
          borderRadius: "8px",
          background: "#0d1117"
        }}
      >
        {/* full-height spacer → scrollbar is honest about all 1000 rows */}
        <div
          data-testid="inner"
          style={{ height: TOTAL * ITEM_HEIGHT + "px", position: "relative" }}
        >
          {items}
        </div>
      </div>

      <div className="flex flex-wrap gap-3 mt-3 text-xs text-[#8b949e]">
        <span data-testid="rendered-count" className="text-[#61dafb]">
          Rendered: {renderedCount} / {TOTAL}
        </span>
        <span>
          · scrollTop {scrollTop}px · start {startIndex} · end {endIndex}
        </span>
      </div>
    </div>
  );
}

createRoot(document.getElementById("root")).render(<VirtualList/>);

2 · Babel compiles JSX → element tree

<VirtualList/> becomes React.createElement(VirtualList). The loop only pushes visibleCount elements — the other 988 rows never become DOM nodes. On scroll, setScrollTop changes startIndex and React reconciles the new short list.

// (hit "compile & render" to see Babel's output)

3 · live React (windowing, proven)

There are 1,000 rows of data, but only ~12 are ever in the DOM. Scroll the box (or let the gold-check scroll it for you): the DOM nodes badge stays ~12 while Rendered reflects the active window — that gap is the whole point.

DOM nodes (live): — / 1000 · gold: count~12 → assert #1 → scroll → assert #201 → re-count~12

intent → pattern

intent	pattern	why
render 10k rows without lag	slice to the visible window; absolute-position each row	~12 DOM nodes regardless of `total`
compute the visible range	`start=floor(scrollTop/h)`; `count=ceil(vp/h)+buffer`	O(1) arithmetic — no scan over data
fake the full scroll height	inner spacer div: `height = total × itemHeight`	scrollbar looks right; browser owns momentum/inertia
paint a row in its slot	`position:absolute; top: i × itemHeight`	no layout shift; each row lands at its exact offset
hide blank flash on fast scroll	overscan: render ±2 rows beyond the viewport edges	covers the gap while React commits the new slice
variable row heights	measure + cache each row's height; recompute cumulative offsets	needs a measurement pass — reach for a library here