0
# Core Virtualization Components
1

2
The essential components for rendering large datasets efficiently through virtualization.
3

4
## Capabilities
5

6
### List Component
7

8
A virtualized list component that renders only visible rows for optimal performance with large datasets.
9

10
```javascript { .api }
11
/**
12
 * Efficiently renders large lists using virtualization
13
 * @param props - List configuration
14
 */
15
function List(props: {
16
  /** Aria label for accessibility */
17
  'aria-label'?: string;
18
  /** Remove fixed height constraint for use with WindowScroller */
19
  autoHeight?: boolean;
20
  /** Optional CSS class name */
21
  className?: string;
22
  /** Estimated row size for initial calculations */
23
  estimatedRowSize?: number;
24
  /** Height constraint for list (determines visible rows) */
25
  height: number;
26
  /** Renderer when no rows are present */
27
  noRowsRenderer?: () => React.Node;
28
  /** Callback with rendered row information */
29
  onRowsRendered?: (params: {overscanStartIndex: number, overscanStopIndex: number, startIndex: number, stopIndex: number}) => void;
30
  /** Scroll event callback */
31
  onScroll?: (params: {clientHeight: number, scrollHeight: number, scrollTop: number}) => void;
32
  /** Custom overscan calculation function */
33
  overscanIndicesGetter?: OverscanIndicesGetter;
34
  /** Number of extra rows to render for smooth scrolling */
35
  overscanRowCount?: number;
36
  /** Fixed height or dynamic height function */
37
  rowHeight: number | ((params: {index: number}) => number);
38
  /** Row rendering function */
39
  rowRenderer: (params: {index: number, key: string, style: object}) => React.Node;
40
  /** Total number of rows */
41
  rowCount: number;
42
  /** Scroll alignment behavior */
43
  scrollToAlignment?: 'auto' | 'end' | 'start' | 'center';
44
  /** Row index to scroll to */
45
  scrollToIndex?: number;
46
  /** Vertical scroll offset */
47
  scrollTop?: number;
48
  /** Inline styles */
49
  style?: object;
50
  /** Tab index for focus */
51
  tabIndex?: number;
52
  /** Width of list */
53
  width: number;
54
}): React.Component;
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
import React from 'react';
61
import { List } from 'react-virtualized';
62

63
// Basic list with fixed row height
64
function BasicList({ items }) {
65
  const rowRenderer = ({ index, key, style }) => (
66
    <div key={key} style={style} className="list-item">
67
      {items[index]}
68
    </div>
69
  );
70

71
  return (
72
    <List
73
      height={400}
74
      width={300}
75
      rowCount={items.length}
76
      rowHeight={50}
77
      rowRenderer={rowRenderer}
78
    />
79
  );
80
}
81

82
// Dynamic height list
83
function DynamicList({ items }) {
84
  const getRowHeight = ({ index }) => {
85
    // Calculate height based on content
86
    return items[index].length * 2 + 40;
87
  };
88

89
  const rowRenderer = ({ index, key, style }) => (
90
    <div key={key} style={style} className="dynamic-item">
91
      <h3>{items[index].title}</h3>
92
      <p>{items[index].description}</p>
93
    </div>
94
  );
95

96
  return (
97
    <List
98
      height={400}
99
      width={300}
100
      rowCount={items.length}
101
      rowHeight={getRowHeight}
102
      rowRenderer={rowRenderer}
103
      estimatedRowSize={80}
104
    />
105
  );
106
}
107
```
108

109
### Grid Component
110

111
A 2D virtualized grid component for rendering tabular data with both horizontal and vertical virtualization.
112

113
```javascript { .api }
114
/**
115
 * Core virtualized grid component for rendering 2D data
116
 * @param props - Grid configuration
117
 */
118
function Grid(props: {
119
  /** Aria label for accessibility */
120
  'aria-label'?: string;
121
  /** Remove fixed height constraint */
122
  autoHeight?: boolean;
123
  /** Optional CSS class name */
124
  className?: string;
125
  /** Total number of columns */
126
  columnCount: number;
127
  /** Fixed width or dynamic width function for columns */
128
  columnWidth: number | ((params: {index: number}) => number);
129
  /** Estimated column size for initial calculations */
130
  estimatedColumnSize?: number;
131
  /** Estimated row size for initial calculations */
132
  estimatedRowSize?: number;
133
  /** Height constraint for grid */
134
  height: number;
135
  /** Renderer when no content is present */
136
  noContentRenderer?: () => React.Node;
137
  /** Callback when cells are rendered */
138
  onSectionRendered?: (params: {columnStartIndex: number, columnStopIndex: number, rowStartIndex: number, rowStopIndex: number}) => void;
139
  /** Scroll event callback */
140
  onScroll?: (params: {clientHeight: number, clientWidth: number, scrollHeight: number, scrollLeft: number, scrollTop: number, scrollWidth: number}) => void;
141
  /** Custom overscan calculation function */
142
  overscanIndicesGetter?: OverscanIndicesGetter;
143
  /** Number of extra columns to render */
144
  overscanColumnCount?: number;
145
  /** Number of extra rows to render */
146
  overscanRowCount?: number;
147
  /** Total number of rows */
148
  rowCount: number;
149
  /** Fixed height or dynamic height function for rows */
150
  rowHeight: number | ((params: {index: number}) => number);
151
  /** Cell rendering function */
152
  cellRenderer: (params: {columnIndex: number, key: string, rowIndex: number, style: object}) => React.Node;
153
  /** Column index to scroll to */
154
  scrollToColumn?: number;
155
  /** Row index to scroll to */
156
  scrollToRow?: number;
157
  /** Scroll alignment for columns */
158
  scrollToAlignment?: 'auto' | 'end' | 'start' | 'center';
159
  /** Horizontal scroll offset */
160
  scrollLeft?: number;
161
  /** Vertical scroll offset */
162
  scrollTop?: number;
163
  /** Inline styles */
164
  style?: object;
165
  /** Tab index for focus */
166
  tabIndex?: number;
167
  /** Width of grid */
168
  width: number;
169
}): React.Component;
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
import React from 'react';
176
import { Grid } from 'react-virtualized';
177

178
// Basic grid with fixed cell sizes
179
function BasicGrid({ data }) {
180
  const cellRenderer = ({ columnIndex, key, rowIndex, style }) => (
181
    <div key={key} style={style} className="grid-cell">
182
      {data[rowIndex][columnIndex]}
183
    </div>
184
  );
185

186
  return (
187
    <Grid
188
      cellRenderer={cellRenderer}
189
      columnCount={data[0].length}
190
      columnWidth={100}
191
      height={400}
192
      rowCount={data.length}
193
      rowHeight={50}
194
      width={600}
195
    />
196
  );
197
}
198

199
// Spreadsheet-like grid with custom sizing
200
function SpreadsheetGrid({ rows, columns }) {
201
  const getColumnWidth = ({ index }) => {
202
    return columns[index].width || 100;
203
  };
204

205
  const cellRenderer = ({ columnIndex, key, rowIndex, style }) => (
206
    <div
207
      key={key}
208
      style={{
209
        ...style,
210
        border: '1px solid #ddd',
211
        padding: '4px',
212
        overflow: 'hidden'
213
      }}
214
    >
215
      {rows[rowIndex][columns[columnIndex].key]}
216
    </div>
217
  );
218

219
  return (
220
    <Grid
221
      cellRenderer={cellRenderer}
222
      columnCount={columns.length}
223
      columnWidth={getColumnWidth}
224
      height={400}
225
      rowCount={rows.length}
226
      rowHeight={35}
227
      width={800}
228
      overscanColumnCount={2}
229
      overscanRowCount={5}
230
    />
231
  );
232
}
233
```
234

235
### Table Component
236

237
A table component with fixed headers and virtualized rows, optimized for displaying structured data.
238

239
```javascript { .api }
240
/**
241
 * Table component with fixed headers and virtualized rows
242
 * @param props - Table configuration
243
 */
244
function Table(props: {
245
  /** Aria label for accessibility */
246
  'aria-label'?: string;
247
  /** Aria labelledby for accessibility */
248
  'aria-labelledby'?: string;
249
  /** Remove fixed height constraint */
250
  autoHeight?: boolean;
251
  /** Column components defining table structure */
252
  children: Column[];
253
  /** Optional CSS class name */
254
  className?: string;
255
  /** Disable header rendering */
256
  disableHeader?: boolean;
257
  /** Estimated row size for calculations */
258
  estimatedRowSize: number;
259
  /** CSS class for inner Grid element */
260
  gridClassName?: string;
261
  /** Inline style for inner Grid element */
262
  gridStyle?: object;
263
  /** CSS class for column headers */
264
  headerClassName?: string;
265
  /** Fixed height of header row */
266
  headerHeight: number;
267
  /** Custom header row renderer */
268
  headerRowRenderer?: (params: {className: string, columns: React.Node[], style: object}) => React.Node;
269
  /** Inline style for headers */
270
  headerStyle?: object;
271
  /** Height constraint for table */
272
  height: number;
273
  /** Optional element ID */
274
  id?: string;
275
  /** Renderer when no rows are present */
276
  noRowsRenderer?: () => React.Node;
277
  /** Column click callback */
278
  onColumnClick?: (params: {columnData: any, dataKey: string}) => void;
279
  /** Header click callback */
280
  onHeaderClick?: (params: {columnData: any, dataKey: string}) => void;
281
  /** Callback when rows are rendered */
282
  onRowsRendered?: (params: {overscanStartIndex: number, overscanStopIndex: number, startIndex: number, stopIndex: number}) => void;
283
  /** Scroll event callback */
284
  onScroll?: (params: {clientHeight: number, scrollHeight: number, scrollTop: number}) => void;
285
  /** Custom overscan calculation */
286
  overscanIndicesGetter?: OverscanIndicesGetter;
287
  /** Number of extra rows to render */
288
  overscanRowCount?: number;
289
  /** Total number of rows */
290
  rowCount: number;
291
  /** Function to get row data by index */
292
  rowGetter: (params: {index: number}) => object;
293
  /** Fixed height or dynamic height function */
294
  rowHeight: number | ((params: {index: number}) => number);
295
  /** Custom row renderer */
296
  rowRenderer?: (params: {className: string, columns: React.Node[], index: number, key: string, onRowClick?: function, onRowDoubleClick?: function, onRowMouseOut?: function, onRowMouseOver?: function, onRowRightClick?: function, rowData: object, style: object}) => React.Node;
297
  /** Sort callback function */
298
  sort?: (params: {sortBy: string, sortDirection: string}) => void;
299
  /** Current sort column */
300
  sortBy?: string;
301
  /** Current sort direction */
302
  sortDirection?: 'ASC' | 'DESC';
303
  /** Row index to scroll to */
304
  scrollToIndex?: number;
305
  /** Scroll alignment behavior */
306
  scrollToAlignment?: 'auto' | 'end' | 'start' | 'center';
307
  /** Vertical scroll offset */
308
  scrollTop?: number;
309
  /** Inline styles */
310
  style?: object;
311
  /** Tab index for focus */
312
  tabIndex?: number;
313
  /** Width of table */
314
  width: number;
315
}): React.Component;
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
import React from 'react';
322
import { Table, Column } from 'react-virtualized';
323

324
// Basic table with sortable columns
325
function UserTable({ users, onSort, sortBy, sortDirection }) {
326
  const rowGetter = ({ index }) => users[index];
327

328
  return (
329
    <Table
330
      width={800}
331
      height={400}
332
      headerHeight={50}
333
      rowHeight={40}
334
      rowCount={users.length}
335
      rowGetter={rowGetter}
336
      sort={onSort}
337
      sortBy={sortBy}
338
      sortDirection={sortDirection}
339
    >
340
      <Column
341
        label="Name"
342
        dataKey="name"
343
        width={200}
344
      />
345
      <Column
346
        label="Email"
347
        dataKey="email"
348
        width={300}
349
      />
350
      <Column
351
        label="Age"
352
        dataKey="age"
353
        width={80}
354
      />
355
      <Column
356
        label="Status"
357
        dataKey="status"
358
        width={120}
359
        cellRenderer={({ rowData }) => (
360
          <span className={`status ${rowData.status}`}>
361
            {rowData.status}
362
          </span>
363
        )}
364
      />
365
    </Table>
366
  );
367
}
368

369
// Advanced table with custom renderers
370
function ProductTable({ products }) {
371
  const rowGetter = ({ index }) => products[index];
372

373
  const priceRenderer = ({ cellData, rowData }) => (
374
    <span className="price">
375
      ${cellData.toFixed(2)}
376
      {rowData.onSale && <span className="sale-badge">SALE</span>}
377
    </span>
378
  );
379

380
  const imageRenderer = ({ cellData }) => (
381
    <img
382
      src={cellData}
383
      alt="Product"
384
      style={{ width: 30, height: 30, borderRadius: '4px' }}
385
    />
386
  );
387

388
  return (
389
    <Table
390
      width={900}
391
      height={500}
392
      headerHeight={60}
393
      rowHeight={50}
394
      rowCount={products.length}
395
      rowGetter={rowGetter}
396
      estimatedRowSize={50}
397
    >
398
      <Column
399
        label="Image"
400
        dataKey="imageUrl"
401
        width={60}
402
        cellRenderer={imageRenderer}
403
        disableSort
404
      />
405
      <Column
406
        label="Product Name"
407
        dataKey="name"
408
        width={250}
409
        flexGrow={1}
410
      />
411
      <Column
412
        label="Category"
413
        dataKey="category"
414
        width={120}
415
      />
416
      <Column
417
        label="Price"
418
        dataKey="price"
419
        width={100}
420
        cellRenderer={priceRenderer}
421
      />
422
      <Column
423
        label="In Stock"
424
        dataKey="inStock"
425
        width={80}
426
        cellRenderer={({ cellData }) => cellData ? '✓' : '✗'}
427
      />
428
    </Table>
429
  );
430
}
431
```