0
# React Virtuoso
1

2
React Virtuoso is a comprehensive virtualization library for React that provides components for efficiently rendering large scrollable lists, grids, and tables. It automatically handles variable item sizes, supports grouping with sticky headers, offers responsive grid layouts, and includes specialized table virtualization—all without manual size calculations or complex configuration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  Virtuoso, 
16
  GroupedVirtuoso, 
17
  VirtuosoGrid, 
18
  TableVirtuoso, 
19
  GroupedTableVirtuoso 
20
} from "react-virtuoso";
21
```
22

23
For specific components:
24

25
```typescript
26
import { Virtuoso } from "react-virtuoso";
27
import type { VirtuosoHandle, VirtuosoProps } from "react-virtuoso";
28
```
29

30
CommonJS:
31

32
```javascript
33
const { Virtuoso, VirtuosoGrid, TableVirtuoso } = require("react-virtuoso");
34
```
35

36
## Basic Usage
37

38
```typescript
39
import React from "react";
40
import { Virtuoso } from "react-virtuoso";
41

42
// Simple list virtualization
43
function MyList() {
44
  const items = Array.from({ length: 10000 }, (_, i) => `Item ${i}`);
45
  
46
  return (
47
    <Virtuoso
48
      style={{ height: '400px' }}
49
      data={items}
50
      itemContent={(index, item) => (
51
        <div style={{ padding: '10px' }}>
52
          {item}
53
        </div>
54
      )}
55
    />
56
  );
57
}
58

59
// Grid virtualization  
60
import { VirtuosoGrid } from "react-virtuoso";
61

62
function MyGrid() {
63
  return (
64
    <VirtuosoGrid
65
      style={{ height: '400px' }}
66
      totalCount={10000}
67
      itemContent={(index) => (
68
        <div style={{ padding: '10px', backgroundColor: '#f0f0f0' }}>
69
          Item {index}
70
        </div>
71
      )}
72
    />
73
  );
74
}
75

76
// Table virtualization
77
import { TableVirtuoso } from "react-virtuoso";
78

79
function MyTable() {
80
  const users = Array.from({ length: 10000 }, (_, i) => ({
81
    id: i,
82
    name: `User ${i}`,
83
    email: `user${i}@example.com`
84
  }));
85

86
  return (
87
    <TableVirtuoso
88
      style={{ height: '400px' }}
89
      data={users}
90
      fixedHeaderContent={() => (
91
        <tr>
92
          <th>Name</th>
93
          <th>Email</th>
94
        </tr>
95
      )}
96
      itemContent={(index, user) => (
97
        <>
98
          <td>{user.name}</td>
99
          <td>{user.email}</td>
100
        </>
101
      )}
102
    />
103
  );
104
}
105
```
106

107
## Architecture
108

109
React Virtuoso is built around several key concepts:
110

111
- **Virtualization Core**: Smart rendering system that only renders visible items plus a configurable buffer
112
- **Size Calculation**: Automatic item size detection with optional fixed or default height optimization  
113
- **Scroll Management**: Advanced scroll handling with smooth scrolling, scroll-to-item, and follow-output capabilities
114
- **Component System**: Pluggable component architecture allowing full customization of rendered elements
115
- **State Management**: Internal state preservation and restoration for navigation scenarios
116
- **Performance Features**: Scroll seek mode for fast scrolling, overscan configuration, and scroll parent customization
117

118
## Capabilities
119

120
### List Virtualization
121

122
Core list virtualization component that handles variable-sized items automatically. Supports infinite scrolling, custom components, and advanced scroll behaviors.
123

124
```typescript { .api }
125
function Virtuoso<D = any, C = any>(props: VirtuosoProps<D, C>): JSX.Element;
126

127
interface VirtuosoProps<D, C> {
128
  data?: readonly D[];
129
  totalCount?: number;
130
  itemContent?: ItemContent<D, C>;
131
  components?: Components<D, C>;
132
  fixedItemHeight?: number;
133
  defaultItemHeight?: number;
134
  followOutput?: FollowOutput;
135
  endReached?: (index: number) => void;
136
  startReached?: (index: number) => void;
137
}
138

139
type ItemContent<D, C> = (index: number, data: D, context: C) => React.ReactNode;
140
```
141

142
[List Virtualization](./list-virtualization.md)
143

144
### Grouped Lists
145

146
Virtualization component for lists with grouped data and sticky group headers. Perfect for categorized content like contact lists or file browsers.
147

148
```typescript { .api }
149
function GroupedVirtuoso<D = any, C = any>(props: GroupedVirtuosoProps<D, C>): JSX.Element;
150

151
interface GroupedVirtuosoProps<D, C> {
152
  groupCounts?: number[];
153
  groupContent?: GroupContent<C>;
154
  itemContent?: GroupItemContent<D, C>;
155
  firstItemIndex?: number;
156
}
157

158
type GroupContent<C> = (index: number, context: C) => React.ReactNode;
159
type GroupItemContent<D, C> = (index: number, groupIndex: number, data: D, context: C) => React.ReactNode;
160
```
161

162
[Grouped Lists](./grouped-lists.md)
163

164
### Grid Virtualization
165

166
Responsive grid virtualization that automatically adapts to container width. Ideal for image galleries, card layouts, and masonry-style interfaces.
167

168
```typescript { .api }
169
function VirtuosoGrid<D = any, C = any>(props: VirtuosoGridProps<D, C>): JSX.Element;
170

171
interface VirtuosoGridProps<D, C> {
172
  data?: readonly D[];
173
  totalCount?: number;
174
  itemContent?: GridItemContent<D, C>;
175
  components?: GridComponents<C>;
176
  listClassName?: string;
177
  itemClassName?: string;
178
}
179

180
type GridItemContent<D, C> = (index: number, data: D, context: C) => React.ReactNode;
181
```
182

183
[Grid Virtualization](./grid-virtualization.md)
184

185
### Table Virtualization
186

187
Specialized virtualization for HTML tables with fixed headers and footers. Maintains proper table semantics while virtualizing large datasets.
188

189
```typescript { .api }
190
function TableVirtuoso<D = any, C = any>(props: TableVirtuosoProps<D, C>): JSX.Element;
191

192
interface TableVirtuosoProps<D, C> {
193
  data?: readonly D[];
194
  itemContent?: ItemContent<D, C>;
195
  fixedHeaderContent?: FixedHeaderContent;
196
  fixedFooterContent?: FixedFooterContent;
197
  components?: TableComponents<D, C>;
198
}
199

200
type FixedHeaderContent = (() => React.ReactNode) | null;
201
type FixedFooterContent = (() => React.ReactNode) | null;
202
```
203

204
[Table Virtualization](./table-virtualization.md)
205

206
### Component Handles and Refs
207

208
All virtualization components provide handle interfaces for programmatic control including scrolling, state management, and viewport queries.
209

210
```typescript { .api }
211
interface VirtuosoHandle {
212
  scrollToIndex(location: FlatIndexLocationWithAlign | number): void;
213
  scrollIntoView(location: FlatScrollIntoViewLocation): void;
214
  scrollTo(location: ScrollToOptions): void;
215
  scrollBy(location: ScrollToOptions): void;
216
  getState(stateCb: StateCallback): void;
217
  autoscrollToBottom(): void;
218
}
219

220
interface FlatIndexLocationWithAlign {
221
  index: number | 'LAST';
222
  align?: 'start' | 'center' | 'end';
223
  behavior?: 'auto' | 'smooth';
224
  offset?: number;
225
}
226
```
227

228
[Component Handles](./component-handles.md)
229

230
## Core Types
231

232
```typescript { .api }
233
interface Components<Data = any, Context = any> {
234
  EmptyPlaceholder?: React.ComponentType<ContextProp<Context>>;
235
  Footer?: React.ComponentType<ContextProp<Context>>;  
236
  Header?: React.ComponentType<ContextProp<Context>>;
237
  Item?: React.ComponentType<ItemProps<Data> & ContextProp<Context>>;
238
  List?: React.ComponentType<ListProps & ContextProp<Context>>;
239
  Scroller?: React.ComponentType<ScrollerProps & ContextProp<Context>>;
240
  ScrollSeekPlaceholder?: React.ComponentType<ScrollSeekPlaceholderProps & ContextProp<Context>>;
241
}
242

243
interface ListRange {
244
  startIndex: number;
245
  endIndex: number;
246
}
247

248
interface ContextProp<C> {
249
  context: C;
250
}
251

252
type ComputeItemKey<D, C> = (index: number, item: D, context: C) => React.Key;
253

254
type FollowOutput = FollowOutputCallback | FollowOutputScalarType;
255
type FollowOutputCallback = (isAtBottom: boolean) => FollowOutputScalarType;
256
type FollowOutputScalarType = 'auto' | 'smooth' | boolean;
257
```
258

259
## Testing & SSR Utilities
260

261
For testing and server-side rendering scenarios, React Virtuoso provides mock contexts that allow components to render with predefined dimensions.
262

263
```typescript { .api }
264
interface VirtuosoMockContextValue {
265
  itemHeight: number;
266
  viewportHeight: number;
267
}
268

269
interface VirtuosoGridMockContextValue {
270
  itemHeight: number;
271
  itemWidth: number;
272
  viewportHeight: number;
273
  viewportWidth: number;
274
}
275

276
const VirtuosoMockContext: React.Context<VirtuosoMockContextValue | undefined>;
277
const VirtuosoGridMockContext: React.Context<VirtuosoGridMockContextValue | undefined>;
278
```
279

280
**Usage Examples:**
281

282
```typescript
283
import { VirtuosoMockContext, Virtuoso } from 'react-virtuoso';
284

285
// For SSR or testing environments
286
function SSRList() {
287
  return (
288
    <VirtuosoMockContext.Provider value={{ itemHeight: 50, viewportHeight: 600 }}>
289
      <Virtuoso
290
        data={items}
291
        itemContent={(index, item) => <div>{item}</div>}
292
      />
293
    </VirtuosoMockContext.Provider>
294
  );
295
}
296

297
// Grid mock context
298
import { VirtuosoGridMockContext, VirtuosoGrid } from 'react-virtuoso';
299

300
function SSRGrid() {
301
  return (
302
    <VirtuosoGridMockContext.Provider value={{ 
303
      itemHeight: 200, 
304
      itemWidth: 250,
305
      viewportHeight: 600,
306
      viewportWidth: 800
307
    }}>
308
      <VirtuosoGrid
309
        totalCount={1000}
310
        itemContent={(index) => <div>Item {index}</div>}
311
      />
312
    </VirtuosoGridMockContext.Provider>
313
  );
314
}