0
# React Virtualized
1

2
React Virtualized is a collection of React components for efficiently rendering large, scrollable lists and tabular data through virtualization techniques. It provides high-performance virtualized components that only render the visible items in large datasets, dramatically improving performance when dealing with thousands of rows or columns.
3

4
## Package Information
5

6
- **Package Name**: react-virtualized
7
- **Package Type**: npm
8
- **Language**: JavaScript (React)
9
- **Installation**: `npm install react-virtualized`
10

11
## Core Imports
12

13
```javascript
14
import { List, Grid, Table, AutoSizer, WindowScroller } from 'react-virtualized';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { List, Grid, Table, AutoSizer, WindowScroller } = require('react-virtualized');
21
```
22

23
Individual component imports for smaller bundle sizes:
24

25
```javascript
26
import List from 'react-virtualized/dist/commonjs/List';
27
import AutoSizer from 'react-virtualized/dist/commonjs/AutoSizer';
28
```
29

30
## Basic Usage
31

32
```javascript
33
import React from 'react';
34
import { List, AutoSizer } from 'react-virtualized';
35

36
// Basic virtualized list
37
function MyList({ items }) {
38
  const rowRenderer = ({ index, key, style }) => (
39
    <div key={key} style={style}>
40
      {items[index]}
41
    </div>
42
  );
43

44
  return (
45
    <AutoSizer>
46
      {({ height, width }) => (
47
        <List
48
          height={height}
49
          width={width}
50
          rowCount={items.length}
51
          rowHeight={50}
52
          rowRenderer={rowRenderer}
53
        />
54
      )}
55
    </AutoSizer>
56
  );
57
}
58
```
59

60
## Architecture
61

62
React Virtualized is built around several key design patterns:
63

64
- **Virtualization Core**: Only renders visible items plus an "overscan" buffer for smooth scrolling
65
- **Measurement System**: Dynamic height/width calculation with caching for performance
66
- **Higher-Order Components**: Decorators like AutoSizer and WindowScroller that enhance other components
67
- **Render Props Pattern**: Components use children functions to provide flexible rendering control
68
- **Position Management**: Sophisticated scrolling and positioning system with alignment options
69

70
## Capabilities
71

72
### Core Virtualization Components
73

74
Essential components for rendering large datasets efficiently.
75

76
```javascript { .api }
77
// Primary virtualized list component
78
function List(props: {
79
  height: number;
80
  width: number;
81
  rowCount: number;
82
  rowHeight: number | ((params: {index: number}) => number);
83
  rowRenderer: (params: {index: number, key: string, style: object}) => React.Node;
84
  // ... additional props
85
}): React.Component;
86

87
// 2D virtualized grid component  
88
function Grid(props: {
89
  columnCount: number;
90
  columnWidth: number | ((params: {index: number}) => number);
91
  height: number;
92
  rowCount: number;
93
  rowHeight: number | ((params: {index: number}) => number);
94
  cellRenderer: (params: {columnIndex: number, rowIndex: number, key: string, style: object}) => React.Node;
95
  // ... additional props
96
}): React.Component;
97

98
// Table with fixed headers and virtualized rows
99
function Table(props: {
100
  width: number;
101
  height: number;
102
  headerHeight: number;
103
  rowHeight: number | ((params: {index: number}) => number);
104
  rowCount: number;
105
  rowGetter: (params: {index: number}) => object;
106
  children: Column[];
107
  // ... additional props  
108
}): React.Component;
109
```
110

111
[Core Components](./core-components.md)
112

113
### Layout and Sizing
114

115
Components that handle automatic sizing and layout management.
116

117
```javascript { .api }
118
// Automatically sizes children to fill available space
119
function AutoSizer(props: {
120
  children: (params: {height: number, width: number}) => React.Node;
121
  disableHeight?: boolean;
122
  disableWidth?: boolean;
123
  // ... additional props
124
}): React.Component;
125

126
// Manages column width distribution
127
function ColumnSizer(props: {
128
  children: (params: {adjustedWidth: number, getColumnWidth: function, registerChild: function}) => React.Node;
129
  columnMaxWidth?: number;
130
  columnMinWidth?: number;
131
  columnCount: number;
132
  width: number;
133
}): React.Component;
134
```
135

136
[Layout Components](./layout-components.md)
137

138
### Dynamic Content and Measurement
139

140
Components for handling dynamic content sizing and infinite loading.
141

142
```javascript { .api }
143
// Measures dynamic cell content for accurate virtualization
144
function CellMeasurer(props: {
145
  cache: CellMeasurerCache;
146
  children: (params: {measure: function, registerChild: function}) => React.Node;
147
  columnIndex?: number;
148
  parent: React.Component;
149
  rowIndex: number;
150
}): React.Component;
151

152
// Cache for CellMeasurer measurements
153
class CellMeasurerCache {
154
  constructor(params: {
155
    defaultHeight?: number;
156
    defaultWidth?: number;
157
    fixedHeight?: boolean;
158
    fixedWidth?: boolean;
159
    minHeight?: number;
160
    minWidth?: number;
161
    keyMapper?: function;
162
  });
163
}
164

165
// Manages loading additional data as user scrolls
166
function InfiniteLoader(props: {
167
  children: (params: {onRowsRendered: function, registerChild: function}) => React.Node;
168
  isRowLoaded: (params: {index: number}) => boolean;
169
  loadMoreRows: (params: {startIndex: number, stopIndex: number}) => Promise;
170
  rowCount: number;
171
  threshold?: number;
172
}): React.Component;
173
```
174

175
[Dynamic Content](./dynamic-content.md)
176

177
### Navigation and Interaction
178

179
Components that add keyboard navigation and scroll synchronization.
180

181
```javascript { .api }
182
// Adds arrow key navigation to virtualized components
183
function ArrowKeyStepper(props: {
184
  children: (params: {onSectionRendered: function, scrollToColumn: number, scrollToRow: number}) => React.Node;
185
  columnCount: number;
186
  rowCount: number;
187
  mode?: 'cells' | 'edges';
188
  // ... additional props
189
}): React.Component;
190

191
// Synchronizes scrolling between multiple components
192
function ScrollSync(props: {
193
  children: (params: {clientHeight: number, clientWidth: number, onScroll: function, scrollHeight: number, scrollLeft: number, scrollTop: number, scrollWidth: number}) => React.Node;
194
}): React.Component;
195

196
// Enables window-based scrolling for components
197
function WindowScroller(props: {
198
  children: (params: {height: number, isScrolling: boolean, onChildScroll: function, scrollTop: number, width: number}) => React.Node;
199
  onResize?: function;
200
  onScroll?: function;
201
  scrollElement?: Element;
202
}): React.Component;
203
```
204

205
[Navigation Components](./navigation-components.md)
206

207
### Specialized Layouts
208

209
Advanced components for complex layout requirements.
210

211
```javascript { .api }
212
// Renders arbitrarily positioned cells efficiently
213
function Collection(props: {
214
  cellCount: number;
215
  cellRenderer: (params: {index: number, key: string, style: object}) => React.Node;
216
  cellSizeAndPositionGetter: (params: {index: number}) => {height: number, width: number, x: number, y: number};
217
  height: number;
218
  width: number;
219
  // ... additional props
220
}): React.Component;
221

222
// Pinterest-style masonry layout
223
function Masonry(props: {
224
  cellCount: number;
225
  cellMeasurerCache: CellMeasurerCache;
226
  cellPositioner: object;
227
  cellRenderer: (params: {index: number, key: string, parent: object, style: object}) => React.Node;
228
  height: number;
229
  width: number;
230
  // ... additional props
231
}): React.Component;
232

233
// Grid with fixed columns and/or rows
234
function MultiGrid(props: {
235
  fixedColumnCount?: number;
236
  fixedRowCount?: number;
237
  columnWidth: number | function;
238
  rowHeight: number | function;
239
  columnCount: number;
240
  rowCount: number;
241
  cellRenderer: function;
242
  width: number;
243
  height: number;
244
  // ... additional props
245
}): React.Component;
246
```
247

248
[Specialized Layouts](./specialized-layouts.md)
249

250
### Table Components
251

252
Specialized components for table functionality.
253

254
```javascript { .api }
255
// Table column descriptor
256
function Column(props: {
257
  cellDataGetter?: (params: {columnData: any, dataKey: string, rowData: any}) => any;
258
  cellRenderer?: (params: {cellData: any, columnData: any, dataKey: string, rowData: any, rowIndex: number}) => React.Node;
259
  dataKey: any;
260
  headerRenderer?: (params: {columnData: any, dataKey: string, disableSort: boolean, label: any, sortBy: string, sortDirection: string}) => React.Node;
261
  width: number;
262
  // ... additional props
263
}): React.Component;
264

265
// Sort direction constants
266
const SortDirection = {
267
  ASC: 'ASC',
268
  DESC: 'DESC'
269
};
270

271
// Sort indicator component
272
function SortIndicator(props: {
273
  sortDirection?: 'ASC' | 'DESC';
274
}): React.Component;
275
```
276

277
[Table Components](./table-components.md)
278

279
### Utility Functions
280

281
Helper functions and utilities for customization.
282

283
```javascript { .api }
284
// Default overscan calculation for standard usage
285
function defaultOverscanIndicesGetter(params: {
286
  cellCount: number;
287
  overscanCellsCount: number;
288
  startIndex: number;
289
  stopIndex: number;
290
}): {overscanStartIndex: number, overscanStopIndex: number};
291

292
// Enhanced overscan calculation for accessibility
293
function accessibilityOverscanIndicesGetter(params: {
294
  cellCount: number;
295
  overscanCellsCount: number;
296
  startIndex: number;
297
  stopIndex: number;
298
}): {overscanStartIndex: number, overscanStopIndex: number};
299

300
// Default cell range renderer
301
function defaultCellRangeRenderer(params: {
302
  cellCache: object;
303
  cellRenderer: function;
304
  columnStartIndex: number;
305
  columnStopIndex: number;
306
  deferredMeasurementCache?: object;
307
  horizontalOffsetAdjustment: number;
308
  isScrolling: boolean;
309
  parent: object;
310
  rowStartIndex: number;
311
  rowStopIndex: number;
312
  styleCache: object;
313
  verticalOffsetAdjustment: number;
314
  visibleColumnIndices: object;
315
  visibleRowIndices: object;
316
}): React.Node[];
317

318
// Multi-column sort utility for tables
319
function createTableMultiSort(sortFunction: function, options?: {defaultSortBy?: Array, defaultSortDirection?: object}): function;
320

321
// Masonry cell positioner creator
322
function createMasonryCellPositioner(params: {
323
  cellMeasurerCache: CellMeasurerCache;
324
  columnCount: number;
325
  columnWidth: number;
326
  spacer?: number;
327
}): object;
328
```
329

330
[Utilities](./utilities.md)
331

332
## Type Definitions
333

334
```javascript { .api }
335
// Common alignment options
336
type Alignment = 'auto' | 'end' | 'start' | 'center';
337

338
// Cell position information
339
interface CellPosition {
340
  columnIndex: number;
341
  rowIndex: number;
342
}
343

344
// Rendered section information
345
interface RenderedSection {
346
  columnStartIndex: number;
347
  columnStopIndex: number;
348
  rowStartIndex: number;
349
  rowStopIndex: number;
350
}
351

352
// Scroll event parameters
353
interface Scroll {
354
  clientHeight: number;
355
  clientWidth: number;
356
  scrollHeight: number;
357
  scrollLeft: number;
358
  scrollTop: number;
359
  scrollWidth: number;
360
}
361

362
// Cell size specification
363
type CellSize = number | ((params: {index: number}) => number);
364

365
// No content renderer function
366
type NoContentRenderer = () => React.Node;
367

368
// Overscan indices getter function
369
type OverscanIndicesGetter = (params: {
370
  cellCount: number;
371
  overscanCellsCount: number;
372
  scrollDirection: number;
373
  startIndex: number;
374
  stopIndex: number;
375
}) => {overscanStartIndex: number, overscanStopIndex: number};
376
```