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