React Virtual (Legacy)

2.10.4 · abandoned · verified Sun Apr 19

React Virtual (version 2.10.4) is a JavaScript library providing a single headless hook (`useVirtual`) for efficiently virtualizing scrollable elements in React applications. It enables the rendering of massive lists, grids, and tables by only mounting the visible items in the DOM, drastically improving performance and memory usage for large datasets. This version, last updated over three years ago, was the predecessor to the more actively maintained and feature-rich `@tanstack/react-virtual` (version 3.x.x), part of the broader TanStack ecosystem. While still functional, it is no longer actively developed or recommended for new projects, with development having shifted entirely to the TanStack-branded successor.

Common errors

```
npm WARN Conflicting peer dependency: react@^17.0.2 npm WARN node_modules/react npm WARN peer react@"^16.6.3 || ^17.0.0" from react-virtual@2.10.4
```
cause `react-virtual` v2.x declares peer dependencies only up to React 17, making it incompatible with React 18+.

fix Downgrade your React version to 16 or 17, or preferably, upgrade your virtualization library to `@tanstack/react-virtual` which supports React 18+.
```
TypeError: Cannot read properties of null (reading 'scrollTop') or similar errors related to `parentRef.current` being null.
```
cause The `parentRef` provided to `useVirtual` is not correctly attached to the scrollable DOM element or is accessed before the ref is populated (e.g., during initial render).

fix Ensure the `parentRef` is correctly assigned to the `div` element that serves as the scrollable container. Also, ensure that any logic dependent on `parentRef.current` is conditionally executed only after `parentRef.current` is available.

Warnings

breaking The `react-virtual` package (v2.x) is effectively abandoned. Its successor is `@tanstack/react-virtual` (v3.x), which introduces breaking API changes including renaming `useVirtual` to `useVirtualizer` and modifying hook signatures and behaviors.
Fix: Migrate to `@tanstack/react-virtual`. This involves changing import paths (`from 'react-virtual'` to `from '@tanstack/react-virtual'`), updating hook names (`useVirtual` to `useVirtualizer`), and adapting to new configuration options. No official migration guide from v2 to v3 exists, requiring manual refactoring.
gotcha `react-virtual` v2.10.4 is incompatible with React 18 due to peer dependency conflicts and internal implementations that are not React 18-friendly.
Fix: Upgrade to `@tanstack/react-virtual` (v3.x), which is designed for modern React versions. If remaining on `react-virtual` v2, you must use React 16 or 17.
gotcha Incorrectly providing the `key` prop for virtualized items can lead to performance issues or unexpected UI behavior, especially when item order changes or items are added/removed.
Fix: Ensure each `virtualItem` rendered has a stable and unique `key` prop. Typically, `virtualRow.index` or `virtualColumn.index` is used, but for dynamic lists where item identity matters more than position, use a unique ID from your data source if available.
gotcha The `estimateSize` option is crucial for performance. Providing an inaccurate `estimateSize` can lead to initial jumpiness or incorrect scrollbar behavior, particularly with variable or dynamic item heights.
Fix: Provide the most accurate possible average `estimateSize` for your items. For truly dynamic sizes, you might need a measurement strategy (though `react-virtual` v2's support for this is less refined than v3's). Consider using libraries that offer automatic size measurement if your item sizes vary significantly.

Install

npm install react-virtual npm
yarn add react-virtual yarn
pnpm add react-virtual pnpm

Imports

useVirtual
wrong:
```
import useVirtual from 'react-virtual'
```
correct:
```
import { useVirtual } from 'react-virtual'
```
The primary virtualization hook. It is a named export, not a default export. Its successor in `@tanstack/react-virtual` is `useVirtualizer` or `useWindowVirtualizer`.
useVirtual
wrong:
```
const useVirtual = require('react-virtual')
```
correct:
```
const { useVirtual } = require('react-virtual')
```
CommonJS `require` syntax for Node.js environments or older bundlers. Still a named export.
VirtualItem
```
import type { VirtualItem } from 'react-virtual'
```
Type import for individual virtualized items, useful for TypeScript projects to correctly type loop variables when mapping `virtualItems`.

Quickstart

This example demonstrates basic row virtualization with fixed item heights, showing how to set up the scroll container and render only the visible rows using the `useVirtual` hook.

import React, { useRef, useCallback, CSSProperties } from 'react';
import { useVirtual } from 'react-virtual';

const RowVirtualizerFixed = () => {
  const parentRef = useRef<HTMLDivElement>(null);
  const rowCount = 10000;

  const rowVirtualizer = useVirtual({
    size: rowCount,
    parentRef,
    estimateSize: useCallback(() => 35, []), // Fixed item height
    overscan: 5,
  });

  return (
    <div
      ref={parentRef}
      style={{
        height: `300px`,
        width: `100%`,
        overflow: `auto`,
      }}
    >
      <div
        style={{
          height: `${rowVirtualizer.totalSize}px`,
          width: `100%`,
          position: `relative`,
        }}
      >
        {rowVirtualizer.virtualItems.map(virtualRow => (
          <div
            key={virtualRow.index}
            style={{
              position: `absolute`,
              top: 0,
              left: 0,
              width: `100%`,
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`,
              background: virtualRow.index % 2 ? '#eee' : '#fafafa',
              display: 'flex',
              alignItems: 'center',
              paddingLeft: '10px',
              borderBottom: '1px solid #ddd',
              boxSizing: 'border-box'
            }}
          >
            Row {virtualRow.index}
          </div>
        ))}
      </div>
    </div>
  );
};

export default RowVirtualizerFixed;

view raw JSON →