0
# RC Virtual List
1
2
RC Virtual List is a high-performance React component for rendering large datasets efficiently through virtualization. It renders only the visible items in the viewport, significantly improving performance and memory usage when displaying thousands of list items, while supporting animations, variable item heights, and custom scrolling behavior.
3
4
## Package Information
5
6
- **Package Name**: rc-virtual-list
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rc-virtual-list`
10
- **Peer Dependencies**: React >=16.9.0, React-DOM >=16.9.0
11
12
## Core Imports
13
14
```typescript
15
import List from "rc-virtual-list";
16
import type { ListRef, ListProps } from "rc-virtual-list";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const List = require("rc-virtual-list");
23
```
24
25
**Note**: Only `ListRef` and `ListProps` types are directly exported. Other types like `RenderFunc`, `ScrollInfo`, etc. are internal to the package and not available for import.
26
27
## Basic Usage
28
29
```typescript
30
import React from "react";
31
import List from "rc-virtual-list";
32
33
const data = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
34
35
function MyVirtualList() {
36
return (
37
<List
38
data={data}
39
height={400}
40
itemHeight={50}
41
itemKey="id"
42
>
43
{(item, index) => (
44
<div style={{ height: 50, padding: "8px" }}>
45
{item.name}
46
</div>
47
)}
48
</List>
49
);
50
}
51
```
52
53
## Architecture
54
55
RC Virtual List uses several key architectural patterns:
56
57
- **Virtual Scrolling Engine**: Only renders items visible in the viewport plus buffer items for smooth scrolling
58
- **Dynamic Height Calculation**: Supports variable item heights with automatic measurement and caching
59
- **Custom Scrollbar System**: Provides styleable scrollbars that work seamlessly with virtualization
60
- **Animation Integration**: Works with React animation libraries through careful lifecycle management
61
- **Multi-directional Support**: Handles both vertical and horizontal scrolling scenarios
62
- **Touch/Mobile Optimization**: Includes specialized handling for touch devices and mobile browsers
63
- **Accessibility Features**: Built-in keyboard navigation and screen reader support
64
65
## Capabilities
66
67
### List Component
68
69
The main virtualized list component providing efficient rendering for large datasets. Handles automatic virtualization, scroll management, and item lifecycle.
70
71
```typescript { .api }
72
const List: <Item = any>(
73
props: ListProps<Item> & { ref?: React.Ref<ListRef> }
74
) => React.ReactElement;
75
76
export interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
77
prefixCls?: string;
78
children: RenderFunc<T>;
79
data: T[];
80
height?: number;
81
itemHeight?: number;
82
fullHeight?: boolean;
83
itemKey: React.Key | ((item: T) => React.Key);
84
component?: string | React.FC<any> | React.ComponentClass<any>;
85
virtual?: boolean;
86
direction?: ScrollBarDirectionType;
87
scrollWidth?: number;
88
styles?: {
89
horizontalScrollBar?: React.CSSProperties;
90
horizontalScrollBarThumb?: React.CSSProperties;
91
verticalScrollBar?: React.CSSProperties;
92
verticalScrollBarThumb?: React.CSSProperties;
93
};
94
showScrollBar?: boolean | 'optional';
95
onScroll?: React.UIEventHandler<HTMLElement>;
96
onVirtualScroll?: (info: ScrollInfo) => void;
97
onVisibleChange?: (visibleList: T[], fullList: T[]) => void;
98
innerProps?: InnerProps;
99
extraRender?: (info: ExtraRenderInfo) => React.ReactNode;
100
}
101
```
102
103
[List Component](./list-component.md)
104
105
### List Reference Interface
106
107
Programmatic control interface for the List component, providing scroll control and state access.
108
109
```typescript { .api }
110
export interface ListRef {
111
nativeElement: HTMLDivElement;
112
scrollTo: ScrollTo;
113
getScrollInfo: () => ScrollInfo;
114
}
115
116
export type ScrollTo = (arg?: number | ScrollConfig | null) => void;
117
118
export interface ScrollInfo {
119
x: number;
120
y: number;
121
}
122
123
export type ScrollConfig = ScrollTarget | ScrollPos;
124
```
125
126
[List Reference](./list-reference.md)
127
128
### Type System
129
130
Internal type definitions used by the List component (not directly exportable).
131
132
```typescript { .api }
133
// Internal type used by ListProps.children
134
type RenderFunc<T> = (
135
item: T,
136
index: number,
137
props: { style: React.CSSProperties; offsetX: number }
138
) => React.ReactNode;
139
140
// Internal type used by ListProps.direction
141
type ScrollBarDirectionType = 'ltr' | 'rtl';
142
143
// Internal type used by ListProps.onVirtualScroll
144
interface ScrollInfo {
145
x: number;
146
y: number;
147
}
148
```
149
150
[Render System](./render-system.md)
151
152
### Scrolling & Navigation
153
154
Advanced scrolling capabilities including programmatic navigation, scroll callbacks, and positioning options.
155
156
```typescript { .api }
157
export type ScrollAlign = 'top' | 'bottom' | 'auto';
158
159
export interface ScrollPos {
160
left?: number;
161
top?: number;
162
}
163
164
export type ScrollTarget =
165
| { index: number; align?: ScrollAlign; offset?: number; }
166
| { key: React.Key; align?: ScrollAlign; offset?: number; };
167
```
168
169
[Scrolling](./scrolling.md)
170
171
## Main Exports
172
173
```typescript { .api }
174
// Default export - the main List component
175
export default List: <Item = any>(
176
props: ListProps<Item> & { ref?: React.Ref<ListRef> }
177
) => React.ReactElement;
178
179
// Named exports - type interfaces only
180
export type { ListRef, ListProps };
181
182
interface ListRef {
183
nativeElement: HTMLDivElement;
184
scrollTo: (arg?: number | ScrollConfig | null) => void;
185
getScrollInfo: () => ScrollInfo;
186
}
187
188
interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
189
// See List Component documentation for complete props interface
190
}
191
192
// Internal supporting types (not exported)
193
interface ScrollInfo {
194
x: number;
195
y: number;
196
}
197
198
type ScrollConfig = ScrollTarget | ScrollPos;
199
type ScrollTarget =
200
| { index: number; align?: ScrollAlign; offset?: number; }
201
| { key: React.Key; align?: ScrollAlign; offset?: number; };
202
interface ScrollPos {
203
left?: number;
204
top?: number;
205
}
206
type ScrollAlign = 'top' | 'bottom' | 'auto';
207
```