{"id":14866,"library":"rc-virtual-list","title":"React Virtual List","description":"rc-virtual-list is a React component designed for efficiently rendering large lists by only rendering items visible within the viewport, significantly improving performance and memory usage compared to rendering all items simultaneously. It supports animations and is compatible with older browsers like IE11+. The package, currently at stable version `3.19.2`, receives regular patch updates, indicating an active maintenance schedule. It is part of the `react-component` ecosystem, known for providing foundational UI components often utilized within Ant Design. Its key differentiators include built-in animation support, broad browser compatibility, and a focus on core virtualization logic without opinionated styling, making it highly adaptable to various design systems. It enables smooth scrolling and interaction even with thousands of data entries by precisely managing what's rendered to the DOM.","status":"active","version":"3.19.2","language":"javascript","source_language":"en","source_url":"https://github.com/react-component/virtual-list","tags":["javascript","react","react-component","virtual-list","typescript"],"install":[{"cmd":"npm install rc-virtual-list","lang":"bash","label":"npm"},{"cmd":"yarn add rc-virtual-list","lang":"bash","label":"yarn"},{"cmd":"pnpm add rc-virtual-list","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency for React applications.","package":"react-dom","optional":false}],"imports":[{"note":"The primary virtual list component is exported as a default export.","wrong":"import { List } from 'rc-virtual-list'; // Incorrect as 'List' is a default export\nconst List = require('rc-virtual-list').List; // Incorrect for default export in CJS","symbol":"List","correct":"import List from 'rc-virtual-list';"},{"note":"TypeScript users can import `ListProps` for type checking the component's properties.","symbol":"ListProps","correct":"import type { ListProps } from 'rc-virtual-list';"},{"note":"For CommonJS environments, the component is accessed via the `.default` property due to it being a default export. This package supports Node.js >= 8.x.","wrong":"const List = require('rc-virtual-list'); // May work in some bundlers, but '.default' is safer for default exports","symbol":"CommonJS require","correct":"const List = require('rc-virtual-list').default;"}],"quickstart":{"code":"import React, { useState, useEffect } from 'react';\nimport List from 'rc-virtual-list';\n\ninterface Item {\n id: number;\n value: string;\n}\n\nconst VirtualizedListExample: React.FC = () => {\n const [data, setData] = useState([]);\n\n useEffect(() => {\n // Generate some mock data for the virtual list\n const generateData = (count: number): Item[] =>\n Array.from({ length: count }).map((_, i) => ({\n id: i,\n value: `Virtual Item ${i + 1}`,\n }));\n setData(generateData(1000)); // Create a list with 1000 items\n }, []);\n\n return (\n
\n

rc-virtual-list Basic Usage

\n

This example demonstrates a virtualized list rendering 1000 items.

\n
\n \n {(item: Item) => (\n \n {item.value}\n
\n )}\n \n
\n \n );\n};\n\nexport default VirtualizedListExample;","lang":"typescript","description":"This quickstart renders a virtualized list with 1000 items, demonstrating basic setup and usage of `rc-virtual-list`."},"warnings":[{"fix":"Monitor the official `rc-virtual-list` GitHub repository for announcements regarding transitions or consolidations. For existing projects, continue using `rc-virtual-list` `3.x.x` unless a migration path is clearly documented. For new projects, evaluate whether to start with `@rc-component/virtual-list` if it appears to be the future stable branch.","message":"The `rc-virtual-list` repository now also publishes `@rc-component/virtual-list` starting from `1.x.x` versions. While `rc-virtual-list` `3.x.x` is still actively maintained, `@rc-component/virtual-list` may represent a future major iteration or a complete renaming of the package. Directly migrating between `rc-virtual-list` and `@rc-component/virtual-list` is likely a breaking change due to potential API differences and import path changes.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure `itemKey` is set to a stable, unique identifier for each item in your `data` array (e.g., `item.id`). If items do not have a natural unique ID, consider generating one, or use a combination of properties that guarantees uniqueness across renders.","message":"The `itemKey` prop is critical for correct and performant rendering in virtualized lists. Using an unstable value (like array `index`) for `itemKey` when the `data` array can change order, or items can be added/removed from the middle, will lead to rendering glitches, incorrect element state, and potential performance issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For lists with dynamically sized items, ensure `itemHeight` is either an accurate average or estimated height. If heights vary significantly, consider implementing mechanisms to dynamically measure item heights or use a virtualized list solution specifically designed for variable height items if `rc-virtual-list`'s API doesn't fully support it (e.g., providing a `measure` prop if available).","message":"If the height of items changes dynamically after initial render, and the `itemHeight` prop is a fixed number, the virtual list may miscalculate scroll positions, leading to unexpected jumps or blank spaces.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"This is an internal change; most users are unaffected. If encountering unexpected DOM-related issues after upgrading, re-evaluate any code that directly or indirectly interacts with the component's underlying DOM structure, and prefer using React refs for direct DOM access instead of relying on `findDOMNode`.","message":"As of `v3.18.4`, internal reliance on `ReactDOM.findDOMNode` has been removed. While this is primarily an internal improvement aligning with modern React practices, projects that might have inadvertently relied on `findDOMNode` being used somewhere within the `rc-virtual-list` component tree (e.g., for specific DOM manipulation hacks) might experience subtle behavioral shifts.","severity":"deprecated","affected_versions":">=3.18.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set the `itemKey` prop to a stable, unique identifier for each item in your `data`. For example, ``.","cause":"`itemKey` prop is either missing or set to an unstable value (like array index) when the list items change.","error":"Each child in a list should have a unique 'key' prop."},{"fix":"Ensure you are using `React.useRef` (or `createRef` for class components) and accessing the method only after the component has rendered and the ref's `current` property is not null. Example: `listRef.current?.scrollTo(offset);`","cause":"Attempting to call an instance method (e.g., `scrollTo`) on the `List` component before it's mounted or if the ref is not properly attached/has not resolved.","error":"TypeError: Cannot read properties of undefined (reading 'scrollTo')"},{"fix":"Verify `itemKey` is unique and stable. If item heights vary, ensure `itemHeight` is an accurate average or estimated height for proper scroll calculations. Check if the `data` prop is changing as expected and not being incorrectly memoized, preventing the list from updating.","cause":"Often related to incorrect `itemHeight` for items with varying heights, incorrect `itemKey` usage, or aggressive memoization preventing re-render when `data` changes.","error":"Items disappear or reappear incorrectly on scroll, or list jumps unexpectedly."}],"ecosystem":"npm"}