Registry / web-framework / react-virtual

react-virtual

library2.10.4jsnpmunverified

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.

web-framework

npm install react-virtual

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-VIRTUAL

react-virtual

web-frameworkjavascriptv2.10.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useVirtual

✓ import { useVirtual } from 'react-virtual'

✗ 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

✓ const { useVirtual } = require('react-virtual')

✗ 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`.

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;

Debug

Known issues

breakingThe `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.

affects: >=2.10.4

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.

affects: >=2.10.4

gotchaIncorrectly 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.

affects: >=2.0.0

gotchaThe `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.

affects: >=2.0.0

Errors

Common errors & fixes

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

`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.

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.

Upgrade

Version history

2.10.4latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React hooks functionality.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tannerlinsley/react-virtual ↗

packagehttps://www.npmjs.com/package/react-virtual ↗