React Virtualization with react-window

A comprehensive guide to react virtualization with react-window with production examples and best practices.

Why Virtualization Matters in Production

Rendering thousands of list items in the DOM is a common performance killer. Each DOM node consumes memory, and layout recalculations become expensive as the list grows. Virtualization solves this by only rendering the items visible in the viewport, plus a small overscan buffer. This reduces DOM nodes from thousands to tens, dramatically improving scroll performance, memory usage, and initial render time. In production, we've seen React apps crash on mobile devices when rendering 10,000+ items without virtualization. The fix: react-window, a lightweight library that handles the math and DOM management for you. It's not a silver bullet—if your items have complex rendering logic, you still need to memoize and optimize. But for long lists, it's the first tool you reach for.

import { FixedSizeList as List } from 'react-window';

const Row = ({ index, style }) => (
  <div style={style}>Row {index}</div>
);

const Example = () => (
  <List
    height={400}
    itemCount={10000}
    itemSize={35}
    width={300}
  >
    {Row}
  </List>
);

FixedSizeList vs VariableSizeList: Choosing the Right Component

react-window provides two primary list components: FixedSizeList and VariableSizeList. FixedSizeList assumes every item has the same height, which allows O(1) calculations for scroll offset and visible range. It's the fastest option. VariableSizeList requires a callback to report each item's size, which adds overhead but handles dynamic content like chat messages or feeds. In production, always start with FixedSizeList. If your items vary in height, measure them once and cache the results. Avoid recalculating sizes on every render. For VariableSizeList, use the itemSize prop as a function that returns the height for a given index. react-window will call it for each visible item. To improve performance, memoize the size function or precompute an array of heights.

import { VariableSizeList as List } from 'react-window';

const itemSizes = Array.from({ length: 1000 }, (_, i) => (i % 2 === 0 ? 50 : 100));

const Row = ({ index, style }) => (
  <div style={style}>Row {index} - height: {itemSizes[index]}px</div>
);

const Example = () => (
  <List
    height={400}
    itemCount={1000}
    itemSize={index => itemSizes[index]}
    width={300}
  >
    {Row}
  </List>
);

Overscan: The Hidden Performance Knob

Overscan controls how many extra items are rendered above and below the visible area. The default is 1 item per side, but in production you may need more to prevent blank flashes during fast scrolling. However, increasing overscan adds DOM nodes. On mobile, a high overscan can negate the benefits of virtualization. We recommend starting with overscanCount={2} and profiling. If you see white flashes, increase it. If frame drops occur, decrease it. react-window also supports overscanCount for both FixedSizeList and VariableSizeList. For grid components, use overscanColumnsCount and overscanRowsCount. In practice, a value of 2-5 works for most apps. For infinite scroll lists, consider a higher overscan to preload data.

import { FixedSizeList as List } from 'react-window';

const Row = ({ index, style }) => (
  <div style={style}>Row {index}</div>
);

const Example = () => (
  <List
    height={400}
    itemCount={10000}
    itemSize={35}
    width={300}
    overscanCount={5}
  >
    {Row}
  </List>
);

ScrollTo and ScrollToItem: Programmatic Control

react-window exposes imperative methods on the list ref: scrollTo(scrollOffset) and scrollToItem(index, align). These are essential for features like 'scroll to top', 'scroll to new message', or restoring scroll position after data changes. scrollToItem accepts alignment: 'auto', 'smart', 'center', 'end', 'start'. In production, use scrollToItem with 'smart' to avoid jarring jumps. For lists that update frequently, debounce scroll calls to avoid layout thrashing. Also, when the list data changes (e.g., items added at the top), you may need to adjust scroll offset manually. react-window doesn't handle this automatically. Store the scroll offset in a ref and restore it after re-render.

import { useRef, useCallback } from 'react';
import { FixedSizeList as List } from 'react-window';

const Example = () => {
  const listRef = useRef();
  const scrollToItem = useCallback(() => {
    listRef.current.scrollToItem(500, 'center');
  }, []);

  return (
    <>
      <button onClick={scrollToItem}>Scroll to item 500</button>
      <List
        ref={listRef}
        height={400}
        itemCount={10000}
        itemSize={35}
        width={300}
      >
        {({ index, style }) => <div style={style}>Row {index}</div>}
      </List>
    </>
  );
};

Grids with FixedSizeGrid and VariableSizeGrid

react-window also provides grid components for two-dimensional virtualized layouts. FixedSizeGrid and VariableSizeGrid work similarly to their list counterparts but require columnCount, columnWidth, rowCount, and rowHeight. Use cases include spreadsheets, image galleries, and calendar views. In production, grids are trickier because both dimensions need virtualization. Always set overscanColumnsCount and overscanRowsCount to avoid blank cells. For VariableSizeGrid, the columnWidth and rowHeight props are functions. Cache these values to avoid recalculating on every render. Grids also support scrollToItem with align for both row and column indices.

import { FixedSizeGrid as Grid } from 'react-window';

const Cell = ({ columnIndex, rowIndex, style }) => (
  <div style={style}>
    Item {rowIndex},{columnIndex}
  </div>
);

const Example = () => (
  <Grid
    columnCount={100}
    columnWidth={100}
    height={400}
    rowCount={1000}
    rowHeight={35}
    width={600}
  >
    {Cell}
  </Grid>
);

Integrating with Infinite Scroll and Data Fetching

Virtualization pairs naturally with infinite scroll. Use a library like react-window-infinite-loader or implement your own. The pattern: render a fixed number of items, and when the user scrolls near the end, fetch more data and append to the list. react-window's onItemsRendered callback provides visibleStartIndex and visibleStopIndex. Use these to detect when the last visible item is near the end. In production, debounce the fetch to avoid multiple requests. Also, handle loading states by rendering a placeholder row at the bottom. When new data arrives, update the itemCount and optionally call scrollToItem to maintain position. Beware of scroll jumps when items are added above the viewport.

import { useState, useCallback, useRef } from 'react';
import { FixedSizeList as List } from 'react-window';

const Example = () => {
  const [items, setItems] = useState(Array.from({ length: 20 }, (_, i) => `Item ${i}`));
  const listRef = useRef();

  const loadMore = useCallback(() => {
    // Simulate fetch
    setTimeout(() => {
      setItems(prev => [...prev, ...Array.from({ length: 20 }, (_, i) => `Item ${prev.length + i}`)]);
    }, 500);
  }, []);

  const handleItemsRendered = useCallback(({ visibleStopIndex }) => {
    if (visibleStopIndex >= items.length - 5) {
      loadMore();
    }
  }, [items.length, loadMore]);

  return (
    <List
      ref={listRef}
      height={400}
      itemCount={items.length}
      itemSize={35}
      width={300}
      onItemsRendered={handleItemsRendered}
    >
      {({ index, style }) => <div style={style}>{items[index]}</div>}
    </List>
  );
};

Memoization and Item Rendering Optimization

react-window re-renders items when the list scrolls. If your item component is expensive, wrap it in React.memo. The style prop passed to each item is a plain object; react-window reuses the same object reference for performance, but if you modify it, you break that optimization. Always apply the style to the outer element and avoid spreading it into child components. For items with complex content, consider using shouldComponentUpdate or PureComponent. In production, we've seen 50% render time reduction by memoizing item components. Also, avoid inline functions in the render prop—define the component outside or use useCallback.

import React from 'react';

const Row = React.memo(({ index, style, data }) => {
  // data is passed via itemData prop
  return (
    <div style={style}>
      {data.items[index]}
    </div>
  );
});

const Example = ({ items }) => (
  <FixedSizeList
    height={400}
    itemCount={items.length}
    itemSize={35}
    width={300}
    itemData={{ items }}
  >
    {Row}
  </FixedSizeList>
);

Handling Dynamic Item Heights with Measurement

When items have unknown heights (e.g., user-generated content), you need to measure them after render. Use a library like react-window-size-listener or a custom ResizeObserver. The pattern: render items with a placeholder height, measure the actual height after mount, and update the size cache. Then call resetAfterIndex on the VariableSizeList ref. In production, batch updates to avoid excessive resets. Also, consider using a fixed height for most items and only variable for exceptions. For images, set a known aspect ratio or use a placeholder until loaded. Measuring on every resize can be expensive; debounce the observer.

import { useState, useRef, useCallback } from 'react';
import { VariableSizeList as List } from 'react-window';

const DynamicHeightList = ({ items }) => {
  const listRef = useRef();
  const sizeMap = useRef({});
  const [ready, setReady] = useState(false);

  const getItemSize = index => sizeMap.current[index] || 50;

  const setItemSize = useCallback((index, size) => {
    sizeMap.current[index] = size;
    listRef.current.resetAfterIndex(index);
  }, []);

  // After mount, measure all visible items
  useEffect(() => {
    setReady(true);
  }, []);

  const Row = ({ index, style }) => (
    <div style={style} ref={el => {
      if (el) {
        const height = el.getBoundingClientRect().height;
        if (height !== sizeMap.current[index]) {
          setItemSize(index, height);
        }
      }
    }}>
      {items[index]}
    </div>
  );

  return (
    <List
      ref={listRef}
      height={400}
      itemCount={items.length}
      itemSize={getItemSize}
      width={300}
    >
      {Row}
    </List>
  );
};

Testing and Debugging Virtualized Lists

Testing virtualized lists requires special care because only a subset of items are rendered. Use react-window's FixedSizeList with a fixed itemCount in tests, and scroll to render specific items. For integration tests, use scrollToItem to bring an item into view before asserting. Avoid snapshot testing the entire list—it will be huge and change on every scroll. Instead, test individual item components. In production, add a debug mode that renders all items (disable virtualization) to compare behavior. Use React DevTools to inspect the list's state for visibleStopIndex and visibleStartIndex. For performance debugging, use the Profiler to measure render times.

import { render, screen } from '@testing-library/react';
import { FixedSizeList as List } from 'react-window';

const Row = ({ index, style }) => (
  <div style={style}>Row {index}</div>
);

test('renders item 500 after scrolling', () => {
  const ref = React.createRef();
  render(
    <List
      ref={ref}
      height={400}
      itemCount={1000}
      itemSize={35}
      width={300}
    >
      {Row}
    </List>
  );
  // Scroll to item 500
  act(() => {
    ref.current.scrollToItem(500);
  });
  expect(screen.getByText('Row 500')).toBeInTheDocument();
});

Production Patterns: Error Boundaries and Fallbacks

Virtualized lists can fail in subtle ways: incorrect item counts, size mismatches, or scroll position corruption. Wrap your list in an error boundary to catch rendering errors. Also, provide a fallback UI when the list fails to load or has zero items. For empty states, render a message outside the list to avoid an empty virtualized container. In production, monitor for layout shifts using the Layout Instability API. If the list jumps unexpectedly, log the scroll offset and item count. Consider using a key prop on the list to force remount when data changes drastically. This is safer than trying to reset internal state.

import React from 'react';
import { FixedSizeList as List } from 'react-window';

class ListErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return <div>List failed to render. Please refresh.</div>;
    }
    return this.props.children;
  }
}

const SafeList = (props) => (
  <ListErrorBoundary>
    <List {...props}>
      {props.children}
    </List>
  </ListErrorBoundary>
);

Alternatives and When to Avoid react-window

react-window is not the only virtualization library. react-virtualized is older and heavier. react-virtuoso offers more features like sticky headers and grouping. TanStack Virtual (formerly react-virtual) is a headless solution that gives you full control. For simple lists, react-window is the best balance of size and performance. Avoid virtualization if your list is small (<100 items) or if items have highly variable heights that change frequently. Also, if you need complex animations during scroll, virtualization may fight with your animation library. In those cases, consider using CSS content-visibility: auto instead, which defers rendering without removing DOM nodes.

/* Alternative: CSS content-visibility */
.list-item {
  content-visibility: auto;
  contain-intrinsic-size: 100px; /* placeholder height */
}

Performance Monitoring and Production Debugging

Once your virtualized list is in production, monitor its performance. Use the Performance API to measure scroll frame rates. Log visibleStartIndex and visibleStopIndex to detect if the list is rendering too many items. Watch for layout shifts using the Cumulative Layout Shift (CLS) metric. If CLS spikes, your item sizes may be inconsistent. Also, monitor memory usage: a growing DOM count indicates a leak or incorrect overscan. In React DevTools, check if item components are being unmounted and remounted unnecessarily. Use why-did-you-render to detect unnecessary re-renders. In production, we added a custom hook that reports render counts per item to our analytics.

import { useEffect, useRef } from 'react';

const useListPerformance = (listRef) => {
  const frameCount = useRef(0);
  const lastTime = useRef(performance.now());

  useEffect(() => {
    const observer = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        if (entry.name === 'scroll') {
          frameCount.current++;
        }
      }
    });
    observer.observe({ entryTypes: ['frame'] });

    return () => observer.disconnect();
  }, []);

  // Report every 10 seconds
  useEffect(() => {
    const interval = setInterval(() => {
      const now = performance.now();
      const fps = frameCount.current / ((now - lastTime.current) / 1000);
      console.log(`Scroll FPS: ${fps.toFixed(1)}`);
      frameCount.current = 0;
      lastTime.current = now;
    }, 10000);
    return () => clearInterval(interval);
  }, []);
};

TanStack Virtual as Modern Headless Standard

TanStack Virtual (formerly React Virtual) is a headless UI library for virtualizing large lists and grids. Unlike react-window, it provides hooks like useVirtualizer that give you full control over rendering without dictating markup. This makes it ideal for complex UIs where you need custom scroll containers, dynamic measurements, or integration with other libraries.

To get started, install @tanstack/react-virtual. The core hook useVirtualizer accepts options for the number of items, estimated size, and the scroll container ref. It returns a virtualizer object with getVirtualItems() and getTotalSize(). You map over virtual items to render only visible rows.

Example with fixed height items: ```jsx import { useVirtualizer } from '@tanstack/react-virtual'; import { useRef } from 'react';

function VirtualList({ items }) { const parentRef = useRef(null); const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, });

return ( <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}> <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}> {virtualizer.getVirtualItems().map((virtualItem) => ( <div key={virtualItem.key} style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: virtualItem.size, transform: translateY(${virtualItem.start}px), }} > {items[virtualItem.index]} </div> ))} </div> </div> ); } ```

TanStack Virtual excels in scenarios requiring dynamic measurements, window scrolling, or reverse infinite scroll. It also supports sticky items, gap measurements, and smooth scrolling. Its headless nature means you can use any UI framework or plain CSS.

However, it has a steeper learning curve than react-window and requires more boilerplate for simple lists. For most production apps with complex requirements, TanStack Virtual is the modern standard.

import { useVirtualizer } from '@tanstack/react-virtual';
import { useRef } from 'react';

function VirtualList({ items }) {
  const parentRef = useRef(null);
  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
  });

  return (
    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualItem) => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: virtualItem.size,
              transform: `translateY(${virtualItem.start}px)`,
            }}
          >
            {items[virtualItem.index]}
          </div>
        ))}
      </div>
    </div>
  );
}

CSS content-visibility: auto as Lightweight Alternative

For lists with fewer than 1000 items, CSS content-visibility: auto offers a simpler, zero-JavaScript alternative to full virtualization. This CSS property tells the browser to skip rendering off-screen elements until they are near the viewport, improving initial load and scroll performance.

To use it, apply content-visibility: auto to each list item. You should also set contain-intrinsic-size to reserve space for items before they are rendered, preventing layout shifts.

Example: ``css .list-item { content-visibility: auto; contain-intrinsic-size: 50px; / height of each item / } ``

This works well for static lists where items have predictable sizes. The browser handles visibility checks automatically. However, it's not a replacement for true virtualization when dealing with thousands of items because all DOM nodes are still present in memory. For lists under 1000 items, the performance gain is often sufficient.

Limitations: content-visibility doesn't work with dynamic heights unless you update contain-intrinsic-size dynamically. It also doesn't reduce memory usage for large datasets. For lists exceeding 1000 items, consider react-window or TanStack Virtual.

Browser support is excellent (Chrome, Firefox, Edge, Safari 15+). It's a great progressive enhancement: start with CSS, then upgrade to a library if performance issues arise.

.list-item {
  content-visibility: auto;
  contain-intrinsic-size: 50px; /* Adjust to your item height */
}

Library Size Comparison Table

When choosing a virtualization library, bundle size matters, especially for performance-critical apps. Below is a comparison of popular React virtualization libraries:

react-window is the smallest and most straightforward, ideal when you need a simple virtualized list with minimal overhead. TanStack Virtual offers more flexibility at a slightly larger size. react-virtuoso packs many built-in features but is heavier. vlist is the lightest but limited to fixed sizes.

For production, consider your trade-offs: bundle size vs. feature set. If you only need a basic list, react-window or vlist are excellent. If you anticipate complex requirements like dynamic heights or infinite scroll, TanStack Virtual provides a good balance. react-virtuoso is great for rapid development with many built-in features.

Always measure actual bundle impact using tools like webpack-bundle-analyzer or esbuild's metafile.

// Example: measuring bundle size with esbuild
// Run: esbuild --bundle --minify --analyze your-entry.js
// This will show the size contribution of each library.