Registry / web-framework / rc-virtual-list

rc-virtual-list

JSON →
library3.19.2jsnpmunverified

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.

npm install rc-virtual-list
INSTALL
IMPORT
SIG · RC-VIRTUAL-LIST
R
rc-virtual-list
web-frameworkjavascriptv3.19.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

List
import List from 'rc-virtual-list';
import { List } from 'rc-virtual-list'; // Incorrect as 'List' is a default export const List = require('rc-virtual-list').List; // Incorrect for default export in CJS
The primary virtual list component is exported as a default export.
ListProps
import type { ListProps } from 'rc-virtual-list';
TypeScript users can import `ListProps` for type checking the component's properties.
CommonJS require
const List = require('rc-virtual-list').default;
const List = require('rc-virtual-list'); // May work in some bundlers, but '.default' is safer for default exports
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.

This quickstart renders a virtualized list with 1000 items, demonstrating basic setup and usage of `rc-virtual-list`.

import React, { useState, useEffect } from 'react'; import List from 'rc-virtual-list'; interface Item { id: number; value: string; } const VirtualizedListExample: React.FC = () => { const [data, setData] = useState<Item[]>([]); useEffect(() => { // Generate some mock data for the virtual list const generateData = (count: number): Item[] => Array.from({ length: count }).map((_, i) => ({ id: i, value: `Virtual Item ${i + 1}`, })); setData(generateData(1000)); // Create a list with 1000 items }, []); return ( <div style={{ padding: 20, maxWidth: 400, border: '1px solid #ccc' }}> <h3>rc-virtual-list Basic Usage</h3> <p>This example demonstrates a virtualized list rendering 1000 items.</p> <div style={{ height: 300, overflow: 'auto', border: '1px solid #eee' }}> <List data={data} height={300} // The fixed height of the scrollable area itemHeight={30} // The estimated height of a single list item itemKey="id" // Unique key property for each item > {(item: Item) => ( <div key={item.id} // Essential for React to correctly manage list elements style={{ padding: '8px 16px', borderBottom: '1px solid #f0f0f0', lineHeight: '1.5' }} > {item.value} </div> )} </List> </div> </div> ); }; export default VirtualizedListExample;
Debug
Known issues
breakingThe `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.
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.
affects: all
gotchaThe `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.
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.
affects: >=1.0.0
gotchaIf 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.
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).
affects: >=1.0.0
deprecatedAs 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.
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`.
affects: >=3.18.4
Errors
Common errors & fixes
Each child in a list should have a unique 'key' prop.
`itemKey` prop is either missing or set to an unstable value (like array index) when the list items change.
fix
Set the `itemKey` prop to a stable, unique identifier for each item in your `data`. For example, `<List data={items} itemKey="id">`.
TypeError: Cannot read properties of undefined (reading 'scrollTo')
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.
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);`
Items disappear or reappear incorrectly on scroll, or list jumps unexpectedly.
Often related to incorrect `itemHeight` for items with varying heights, incorrect `itemKey` usage, or aggressive memoization preventing re-render when `data` changes.
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.
Upgrade
Version history
3.19.2latest on npm
Audit
Dependencies
reactrequiredPeer dependency for React applications.
react-domrequiredPeer dependency for React applications.
Agent activity
4 hits · last 30 days
node
4
Resources
rc-virtual-list — npm install rc-virtual-list · libregistry