{"id":11905,"library":"react-virtual","title":"React Virtual (Legacy)","description":"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.","status":"abandoned","version":"2.10.4","language":"javascript","source_language":"en","source_url":"https://github.com/tannerlinsley/react-virtual","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-virtual","lang":"bash","label":"npm"},{"cmd":"yarn add react-virtual","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-virtual","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React hooks functionality.","package":"react","optional":false}],"imports":[{"note":"The primary virtualization hook. It is a named export, not a default export. Its successor in `@tanstack/react-virtual` is `useVirtualizer` or `useWindowVirtualizer`.","wrong":"import useVirtual from 'react-virtual'","symbol":"useVirtual","correct":"import { useVirtual } from 'react-virtual'"},{"note":"CommonJS `require` syntax for Node.js environments or older bundlers. Still a named export.","wrong":"const useVirtual = require('react-virtual')","symbol":"useVirtual","correct":"const { useVirtual } = require('react-virtual')"},{"note":"Type import for individual virtualized items, useful for TypeScript projects to correctly type loop variables when mapping `virtualItems`.","symbol":"VirtualItem","correct":"import type { VirtualItem } from 'react-virtual'"}],"quickstart":{"code":"import React, { useRef, useCallback, CSSProperties } from 'react';\nimport { useVirtual } from 'react-virtual';\n\nconst RowVirtualizerFixed = () => {\n  const parentRef = useRef<HTMLDivElement>(null);\n  const rowCount = 10000;\n\n  const rowVirtualizer = useVirtual({\n    size: rowCount,\n    parentRef,\n    estimateSize: useCallback(() => 35, []), // Fixed item height\n    overscan: 5,\n  });\n\n  return (\n    <div\n      ref={parentRef}\n      style={{\n        height: `300px`,\n        width: `100%`,\n        overflow: `auto`,\n      }}\n    >\n      <div\n        style={{\n          height: `${rowVirtualizer.totalSize}px`,\n          width: `100%`,\n          position: `relative`,\n        }}\n      >\n        {rowVirtualizer.virtualItems.map(virtualRow => (\n          <div\n            key={virtualRow.index}\n            style={{\n              position: `absolute`,\n              top: 0,\n              left: 0,\n              width: `100%`,\n              height: `${virtualRow.size}px`,\n              transform: `translateY(${virtualRow.start}px)`,\n              background: virtualRow.index % 2 ? '#eee' : '#fafafa',\n              display: 'flex',\n              alignItems: 'center',\n              paddingLeft: '10px',\n              borderBottom: '1px solid #ddd',\n              boxSizing: 'border-box'\n            }}\n          >\n            Row {virtualRow.index}\n          </div>\n        ))}\n      </div>\n    </div>\n  );\n};\n\nexport default RowVirtualizerFixed;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.10.4"},{"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.","message":"`react-virtual` v2.10.4 is incompatible with React 18 due to peer dependency conflicts and internal implementations that are not React 18-friendly.","severity":"gotcha","affected_versions":">=2.10.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Downgrade your React version to 16 or 17, or preferably, upgrade your virtualization library to `@tanstack/react-virtual` which supports React 18+.","cause":"`react-virtual` v2.x declares peer dependencies only up to React 17, making it incompatible with React 18+.","error":"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"},{"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.","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).","error":"TypeError: Cannot read properties of null (reading 'scrollTop') or similar errors related to `parentRef.current` being null."}],"ecosystem":"npm"}