0
# React Window
1

2
React Window is a high-performance virtualization library for React applications that enables efficient rendering of large datasets in lists and grids. The library provides two core components - List and Grid - that only render visible items in the viewport, dramatically improving performance when dealing with thousands or millions of data items.
3

4
## Package Information
5

6
- **Package Name**: react-window
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-window`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Grid, 
16
  List, 
17
  useGridRef, 
18
  useGridCallbackRef,
19
  useListRef, 
20
  useListCallbackRef,
21
  getScrollbarSize 
22
} from "react-window";
23
import type { 
24
  GridProps, 
25
  ListProps, 
26
  GridImperativeAPI, 
27
  ListImperativeAPI,
28
  CellComponentProps,
29
  RowComponentProps,
30
  Align
31
} from "react-window";
32
```
33

34
For CommonJS:
35

36
```javascript
37
const { 
38
  Grid, 
39
  List, 
40
  useGridRef, 
41
  useGridCallbackRef,
42
  useListRef, 
43
  useListCallbackRef,
44
  getScrollbarSize 
45
} = require("react-window");
46
```
47

48
## Basic Usage
49

50
### List Component
51

52
```typescript
53
import React from "react";
54
import { List } from "react-window";
55

56
const MyList = () => {
57
  const items = Array.from({ length: 10000 }, (_, index) => `Item ${index}`);
58

59
  const RowComponent = ({ index, style }: { index: number; style: React.CSSProperties }) => (
60
    <div style={style}>
61
      {items[index]}
62
    </div>
63
  );
64

65
  return (
66
    <List
67
      rowComponent={RowComponent}
68
      rowCount={items.length}
69
      rowHeight={35}
70
      rowProps={{}}
71
      style={{ height: 400, width: 300 }}
72
    />
73
  );
74
};
75
```
76

77
### Grid Component  
78

79
```typescript
80
import React from "react";
81
import { Grid } from "react-window";
82

83
const MyGrid = () => {
84
  const CellComponent = ({ 
85
    columnIndex, 
86
    rowIndex, 
87
    style 
88
  }: { 
89
    columnIndex: number; 
90
    rowIndex: number; 
91
    style: React.CSSProperties;
92
  }) => (
93
    <div style={style}>
94
      Cell {rowIndex},{columnIndex}
95
    </div>
96
  );
97

98
  return (
99
    <Grid
100
      cellComponent={CellComponent}
101
      cellProps={{}}
102
      columnCount={100}
103
      columnWidth={100}
104
      rowCount={100}
105
      rowHeight={50}
106
      style={{ height: 400, width: 500 }}
107
    />
108
  );
109
};
110
```
111

112
## Architecture
113

114
React Window is built around several key components:
115

116
- **Virtualization Core**: Smart rendering algorithm that calculates visible items and manages DOM efficiently
117
- **Component System**: Grid and List components that handle 2D and 1D data respectively
118
- **Imperative APIs**: Ref-based APIs for programmatic scrolling and element access
119
- **Type System**: Full TypeScript support with generic type preservation for custom props
120
- **Hook Utilities**: Convenience hooks for proper TypeScript ref management
121

122
## Capabilities
123

124
### List Virtualization
125

126
One-dimensional virtualized scrolling for large lists with support for variable row heights, custom row rendering, and efficient item positioning.
127

128
```typescript { .api }
129
function List<RowProps extends object>(props: ListProps<RowProps>): JSX.Element;
130

131
interface ListProps<RowProps extends object> {
132
  rowComponent: (props: { index: number; style: CSSProperties } & RowProps) => ReactNode;
133
  rowCount: number;
134
  rowHeight: number | string | ((index: number, rowProps: RowProps) => number);
135
  rowProps: RowProps;
136
  listRef?: Ref<ListImperativeAPI>;
137
  onRowsRendered?: (args: { startIndex: number; stopIndex: number }) => void;
138
  onResize?: (size: { height: number; width: number }, prevSize: { height: number; width: number }) => void;
139
  overscanCount?: number;
140
  className?: string;
141
  style?: CSSProperties;
142
  defaultHeight?: number;
143
}
144
```
145

146
[List Virtualization](./list-virtualization.md)
147

148
### Grid Virtualization
149

150
Two-dimensional virtualized scrolling for large grids with support for variable cell sizes, custom cell rendering, and efficient positioning for both rows and columns.
151

152
```typescript { .api }
153
function Grid<CellProps extends object>(props: GridProps<CellProps>): JSX.Element;
154

155
interface GridProps<CellProps extends object> {
156
  cellComponent: (props: { columnIndex: number; rowIndex: number; style: CSSProperties } & CellProps) => ReactNode;
157
  cellProps: CellProps;
158
  columnCount: number;
159
  columnWidth: number | string | ((index: number, cellProps: CellProps) => number);
160
  rowCount: number;
161
  rowHeight: number | string | ((index: number, cellProps: CellProps) => number);
162
  gridRef?: Ref<GridImperativeAPI>;
163
  onCellsRendered?: (args: { columnStartIndex: number; columnStopIndex: number; rowStartIndex: number; rowStopIndex: number }) => void;
164
  onResize?: (size: { height: number; width: number }, prevSize: { height: number; width: number }) => void;
165
  overscanCount?: number;
166
  className?: string;
167
  style?: CSSProperties;
168
  dir?: "ltr" | "rtl";
169
  defaultHeight?: number;
170
  defaultWidth?: number;
171
}
172
```
173

174
[Grid Virtualization](./grid-virtualization.md)
175

176
### Imperative Scrolling APIs
177

178
Programmatic scrolling controls for both List and Grid components with smooth scrolling options and alignment controls.
179

180
```typescript { .api }
181
interface ListImperativeAPI {
182
  get element(): HTMLDivElement | null;
183
  scrollToRow(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
184
}
185

186
interface GridImperativeAPI {
187
  get element(): HTMLDivElement | null;
188
  scrollToCell(params: { rowIndex: number; columnIndex: number; rowAlign?: Align; columnAlign?: Align; behavior?: ScrollBehavior }): void;
189
  scrollToRow(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
190
  scrollToColumn(params: { index: number; align?: Align; behavior?: ScrollBehavior }): void;
191
}
192
```
193

194
[Imperative APIs](./imperative-apis.md)
195

196
### TypeScript Hook Utilities
197

198
Convenience hooks for creating properly typed refs for Grid and List components, supporting both regular refs and callback refs.
199

200
```typescript { .api }
201
function useGridRef(): RefObject<GridImperativeAPI>;
202
function useGridCallbackRef(): [GridImperativeAPI | null, (instance: GridImperativeAPI | null) => void];
203
function useListRef(): RefObject<ListImperativeAPI>;
204
function useListCallbackRef(): [ListImperativeAPI | null, (instance: ListImperativeAPI | null) => void];
205
```
206

207
[TypeScript Utilities](./typescript-utilities.md)
208

209
## Types
210

211
```typescript { .api }
212
type Align = "auto" | "center" | "end" | "smart" | "start";
213

214
interface CellComponentProps<CellProps extends object = object> {
215
  columnIndex: number;
216
  rowIndex: number;
217
  style: CSSProperties;
218
}
219

220
interface RowComponentProps<RowProps extends object = object> {
221
  index: number;
222
  style: CSSProperties;
223
}
224
```
225

226
## Utilities
227

228
### Scrollbar Size Detection
229

230
Utility function for detecting browser scrollbar dimensions, useful for layout calculations.
231

232
```typescript { .api }
233
function getScrollbarSize(recalculate?: boolean): number;
234
```