React Virtualization Patterns

Virtualization renders only visible items, enabling smooth scrolling of large lists. Here's how to implement it.

Why Virtualization?#

// Problem: Rendering 10,000 items
function SlowList({ items }: { items: Item[] }) {
  return (
    <ul>
      {items.map(item => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}
// Creates 10,000 DOM nodes = slow initial render, high memory

// Solution: Render only visible items (~20-50)
function FastList({ items }: { items: Item[] }) {
  // Only renders items in viewport
  return <VirtualizedList items={items} />;
}
// Creates ~30 DOM nodes = fast render, low memory

react-window#

import { FixedSizeList } from 'react-window';

interface Item {
  id: string;
  name: string;
}

function VirtualList({ items }: { items: Item[] }) {
  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (
    <div style={style} className="list-item">
      {items[index].name}
    </div>
  );

  return (
    <FixedSizeList
      height={400}
      width="100%"
      itemCount={items.length}
      itemSize={50}
    >
      {Row}
    </FixedSizeList>
  );
}

// With memoization
const Row = memo(({ data, index, style }: {
  data: Item[];
  index: number;
  style: React.CSSProperties;
}) => (
  <div style={style}>
    {data[index].name}
  </div>
));

function OptimizedList({ items }: { items: Item[] }) {
  return (
    <FixedSizeList
      height={400}
      width="100%"
      itemCount={items.length}
      itemSize={50}
      itemData={items}
    >
      {Row}
    </FixedSizeList>
  );
}

Variable Size List#

import { VariableSizeList } from 'react-window';

function VariableList({ items }: { items: Item[] }) {
  const listRef = useRef<VariableSizeList>(null);

  // Calculate item height based on content
  const getItemSize = (index: number) => {
    const item = items[index];
    const baseHeight = 50;
    const lineHeight = 20;
    const lines = Math.ceil(item.description.length / 50);
    return baseHeight + (lines * lineHeight);
  };

  // Reset cache when items change
  useEffect(() => {
    listRef.current?.resetAfterIndex(0);
  }, [items]);

  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => (
    <div style={style} className="variable-item">
      <h3>{items[index].name}</h3>
      <p>{items[index].description}</p>
    </div>
  );

  return (
    <VariableSizeList
      ref={listRef}
      height={400}
      width="100%"
      itemCount={items.length}
      itemSize={getItemSize}
      estimatedItemSize={80}
    >
      {Row}
    </VariableSizeList>
  );
}

Virtual Grid#

import { FixedSizeGrid } from 'react-window';

function VirtualGrid({ items, columnCount = 4 }: {
  items: Item[];
  columnCount?: number;
}) {
  const rowCount = Math.ceil(items.length / columnCount);

  const Cell = ({ columnIndex, rowIndex, style }: {
    columnIndex: number;
    rowIndex: number;
    style: React.CSSProperties;
  }) => {
    const index = rowIndex * columnCount + columnIndex;
    if (index >= items.length) return null;

    const item = items[index];

    return (
      <div style={style} className="grid-cell">
        <img src={item.image} alt={item.name} />
        <span>{item.name}</span>
      </div>
    );
  };

  return (
    <FixedSizeGrid
      height={600}
      width={800}
      columnCount={columnCount}
      columnWidth={200}
      rowCount={rowCount}
      rowHeight={250}
    >
      {Cell}
    </FixedSizeGrid>
  );
}

TanStack Virtual#

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

function TanStackList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    overscan: 5,
  });

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

// Dynamic sizing
function DynamicList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 100,
    measureElement: (element) => element.getBoundingClientRect().height,
  });

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

Infinite Scroll#

import { FixedSizeList } from 'react-window';
import InfiniteLoader from 'react-window-infinite-loader';

function InfiniteList({
  hasNextPage,
  isNextPageLoading,
  items,
  loadNextPage,
}: {
  hasNextPage: boolean;
  isNextPageLoading: boolean;
  items: Item[];
  loadNextPage: () => Promise<void>;
}) {
  const itemCount = hasNextPage ? items.length + 1 : items.length;

  const isItemLoaded = (index: number) => !hasNextPage || index < items.length;

  const Row = ({ index, style }: { index: number; style: React.CSSProperties }) => {
    if (!isItemLoaded(index)) {
      return <div style={style}>Loading...</div>;
    }

    return (
      <div style={style}>
        {items[index].name}
      </div>
    );
  };

  return (
    <InfiniteLoader
      isItemLoaded={isItemLoaded}
      itemCount={itemCount}
      loadMoreItems={isNextPageLoading ? () => {} : loadNextPage}
    >
      {({ onItemsRendered, ref }) => (
        <FixedSizeList
          ref={ref}
          height={400}
          width="100%"
          itemCount={itemCount}
          itemSize={50}
          onItemsRendered={onItemsRendered}
        >
          {Row}
        </FixedSizeList>
      )}
    </InfiniteLoader>
  );
}

Custom Virtualization#

function useVirtualList<T>({
  items,
  itemHeight,
  containerHeight,
  overscan = 3,
}: {
  items: T[];
  itemHeight: number;
  containerHeight: number;
  overscan?: number;
}) {
  const [scrollTop, setScrollTop] = useState(0);

  const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
  const endIndex = Math.min(
    items.length - 1,
    Math.ceil((scrollTop + containerHeight) / itemHeight) + overscan
  );

  const visibleItems = items.slice(startIndex, endIndex + 1).map((item, index) => ({
    item,
    index: startIndex + index,
    style: {
      position: 'absolute' as const,
      top: (startIndex + index) * itemHeight,
      height: itemHeight,
      width: '100%',
    },
  }));

  const totalHeight = items.length * itemHeight;

  const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
    setScrollTop(e.currentTarget.scrollTop);
  };

  return { visibleItems, totalHeight, handleScroll };
}

// Usage
function CustomVirtualList({ items }: { items: Item[] }) {
  const { visibleItems, totalHeight, handleScroll } = useVirtualList({
    items,
    itemHeight: 50,
    containerHeight: 400,
  });

  return (
    <div
      style={{ height: 400, overflow: 'auto' }}
      onScroll={handleScroll}
    >
      <div style={{ height: totalHeight, position: 'relative' }}>
        {visibleItems.map(({ item, index, style }) => (
          <div key={item.id} style={style}>
            {item.name}
          </div>
        ))}
      </div>
    </div>
  );
}

Windowed Table#

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

function VirtualTable({ data, columns }: {
  data: Record<string, any>[];
  columns: { key: string; header: string; width: number }[];
}) {
  const parentRef = useRef<HTMLDivElement>(null);

  const rowVirtualizer = useVirtualizer({
    count: data.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 40,
    overscan: 10,
  });

  return (
    <div ref={parentRef} style={{ height: 500, overflow: 'auto' }}>
      <table style={{ width: '100%', borderCollapse: 'collapse' }}>
        <thead style={{ position: 'sticky', top: 0, background: 'white' }}>
          <tr>
            {columns.map(col => (
              <th key={col.key} style={{ width: col.width }}>
                {col.header}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          <tr style={{ height: rowVirtualizer.getTotalSize() }}>
            <td colSpan={columns.length} style={{ padding: 0 }}>
              <div style={{ position: 'relative', height: '100%' }}>
                {rowVirtualizer.getVirtualItems().map(virtualRow => (
                  <div
                    key={virtualRow.key}
                    style={{
                      position: 'absolute',
                      top: virtualRow.start,
                      width: '100%',
                      height: virtualRow.size,
                      display: 'flex',
                    }}
                  >
                    {columns.map(col => (
                      <div key={col.key} style={{ width: col.width }}>
                        {data[virtualRow.index][col.key]}
                      </div>
                    ))}
                  </div>
                ))}
              </div>
            </td>
          </tr>
        </tbody>
      </table>
    </div>
  );
}

Scroll Restoration#

function VirtualListWithRestore({ items }: { items: Item[] }) {
  const listRef = useRef<FixedSizeList>(null);
  const scrollKey = 'list-scroll-position';

  // Restore scroll position
  useEffect(() => {
    const savedPosition = sessionStorage.getItem(scrollKey);
    if (savedPosition && listRef.current) {
      listRef.current.scrollTo(parseInt(savedPosition, 10));
    }
  }, []);

  // Save scroll position
  const handleScroll = ({ scrollOffset }: { scrollOffset: number }) => {
    sessionStorage.setItem(scrollKey, String(scrollOffset));
  };

  return (
    <FixedSizeList
      ref={listRef}
      height={400}
      width="100%"
      itemCount={items.length}
      itemSize={50}
      onScroll={handleScroll}
    >
      {Row}
    </FixedSizeList>
  );
}

Best Practices#

Implementation:
✓ Use overscan for smooth scrolling
✓ Memoize row components
✓ Handle dynamic heights properly
✓ Reset virtualizer on data changes

Performance:
✓ Avoid inline styles in rows
✓ Use itemData for shared data
✓ Debounce scroll handlers
✓ Profile with React DevTools

UX:
✓ Show loading placeholders
✓ Preserve scroll position
✓ Handle empty states
✓ Support keyboard navigation

Virtualization enables smooth rendering of large lists by only rendering visible items. Use react-window for simple cases, TanStack Virtual for dynamic sizing, and implement infinite scroll for paginated data. Always memoize row components and handle scroll restoration.