0
# List Component
1

2
The main virtualized list component providing efficient rendering for large datasets through viewport-based virtualization.
3

4
## Capabilities
5

6
### List Component
7

8
The primary React component that renders virtualized lists with automatic optimization.
9

10
```typescript { .api }
11
/**
12
 * Main virtual list component with full virtualization support
13
 * @param props - List configuration and data
14
 * @returns Virtualized list React element
15
 */
16
const List: <Item = any>(
17
  props: ListProps<Item> & { ref?: React.Ref<ListRef> }
18
) => React.ReactElement;
19

20
interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'> {
21
  /** CSS class prefix for styling */
22
  prefixCls?: string;
23
  /** Render function for each list item */
24
  children: RenderFunc<T>;
25
  /** Array of data items to render */
26
  data: T[];
27
  /** Container height in pixels - required for virtualization */
28
  height?: number;
29
  /** Minimum height of each item in pixels */
30
  itemHeight?: number;
31
  /** If true, uses height; if false, uses maxHeight */
32
  fullHeight?: boolean;
33
  /** Key extraction function or property name for item identification */
34
  itemKey: React.Key | ((item: T) => React.Key);
35
  /** Custom container component (default: 'div') */
36
  component?: string | React.FC<any> | React.ComponentClass<any>;
37
  /** Enable/disable virtualization (default: true when height/itemHeight provided) */
38
  virtual?: boolean;
39
  /** Text direction for RTL support */
40
  direction?: ScrollBarDirectionType;
41
  /** Enable horizontal scrolling with specified scroll width */
42
  scrollWidth?: number;
43
  /** Custom styles for scrollbars */
44
  styles?: {
45
    horizontalScrollBar?: React.CSSProperties;
46
    horizontalScrollBarThumb?: React.CSSProperties;
47
    verticalScrollBar?: React.CSSProperties;
48
    verticalScrollBarThumb?: React.CSSProperties;
49
  };
50
  /** Control scrollbar visibility */
51
  showScrollBar?: boolean | 'optional';
52
  /** Native scroll event handler */
53
  onScroll?: React.UIEventHandler<HTMLElement>;
54
  /** Virtual scroll position callback */
55
  onVirtualScroll?: (info: ScrollInfo) => void;
56
  /** Callback when visible items change */
57
  onVisibleChange?: (visibleList: T[], fullList: T[]) => void;
58
  /** Props passed to inner container for accessibility */
59
  innerProps?: InnerProps;
60
  /** Custom content renderer for advanced use cases */
61
  extraRender?: (info: ExtraRenderInfo) => React.ReactNode;
62
}
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import React from "react";
69
import List from "rc-virtual-list";
70

71
// Basic virtualized list
72
const BasicList = () => {
73
  const data = Array.from({ length: 1000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
74
  
75
  return (
76
    <List
77
      data={data}
78
      height={300}
79
      itemHeight={40}
80
      itemKey="id"
81
    >
82
      {(item) => <div>{item.text}</div>}
83
    </List>
84
  );
85
};
86

87
// Custom component with styling
88
const StyledList = () => {
89
  const data = [/* ... */];
90
  
91
  return (
92
    <List
93
      component="ul"
94
      className="my-list"
95
      data={data}
96
      height={400}
97
      itemHeight={50}
98
      itemKey="id"
99
      styles={{
100
        verticalScrollBar: { background: '#f0f0f0' },
101
        verticalScrollBarThumb: { background: '#666' }
102
      }}
103
    >
104
      {(item) => <li>{item.name}</li>}
105
    </List>
106
  );
107
};
108

109
// With scroll callbacks
110
const CallbackList = () => {
111
  const handleVirtualScroll = (info) => {
112
    console.log('Virtual scroll position:', info.x, info.y);
113
  };
114
  
115
  const handleVisibleChange = (visibleItems, allItems) => {
116
    console.log(`Showing ${visibleItems.length} of ${allItems.length} items`);
117
  };
118
  
119
  return (
120
    <List
121
      data={data}
122
      height={300}
123
      itemHeight={40}
124
      itemKey="id"
125
      onVirtualScroll={handleVirtualScroll}
126
      onVisibleChange={handleVisibleChange}
127
    >
128
      {(item) => <div>{item.content}</div>}
129
    </List>
130
  );
131
};
132
```
133

134
### Render Function
135

136
Function that renders individual list items with positioning information.
137

138
```typescript { .api }
139
/**
140
 * Function for rendering individual list items
141
 * @param item - The data item to render
142
 * @param index - Index of the item in the data array
143
 * @param props - Additional properties including style and offset information
144
 * @returns React node to render
145
 */
146
type RenderFunc<T> = (
147
  item: T,
148
  index: number,
149
  props: { 
150
    style: React.CSSProperties; 
151
    offsetX: number;
152
  }
153
) => React.ReactNode;
154
```
155

156
The render function receives three parameters:
157
- `item`: The actual data item from the `data` array
158
- `index`: The position of the item in the array
159
- `props.style`: CSS styles for proper positioning (important for virtualization)
160
- `props.offsetX`: Horizontal offset for horizontal scrolling scenarios
161

162
### Scroll Direction Type
163

164
```typescript { .api }
165
type ScrollBarDirectionType = 'ltr' | 'rtl';
166
```
167

168
### Inner Props Interface
169

170
```typescript { .api }
171
interface InnerProps {
172
  [key: string]: any;
173
}
174
```
175

176
Used to pass additional props to the inner container element, primarily for accessibility attributes like `aria-*` properties.
177

178
### Performance Considerations
179

180
- **itemHeight**: Providing accurate `itemHeight` improves initial rendering performance
181
- **itemKey**: Use stable, unique keys to optimize re-rendering
182
- **virtual**: Can be disabled for small lists to avoid virtualization overhead
183
- **data**: Avoid recreating the data array on each render to prevent unnecessary updates