TanStack · tannerlinsley · Dec 24, 2025 · piecyk · Jan 2, 2026 · piecyk
diff --git a/docs/config.json b/docs/config.json
@@ -112,6 +112,18 @@
  {
  "label": "react",
  "children": [
+ {
+ "to": "framework/react/examples/list",
+ "label": "List"
+ },
+ {
+ "to": "framework/react/examples/horizontal-list",
+ "label": "Horizontal List"
+ },
+ {
+ "to": "framework/react/examples/grid",
+ "label": "Grid"
+ },
  {
  "to": "framework/react/examples/fixed",
  "label": "Fixed"

diff --git a/examples/react/grid/index.html b/examples/react/grid/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Grid Virtualization Example</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/examples/react/grid/package.json b/examples/react/grid/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "tanstack-react-virtual-example-grid",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc && vite build",
+ "serve": "vite preview"
+ },
+ "dependencies": {
+ "@faker-js/faker": "^8.4.1",
+ "@tanstack/react-virtual": "^3.13.13",
+ "react": "^18.3.1",
+ "react-dom": "^18.3.1"
+ },
+ "devDependencies": {
+ "@types/node": "^24.5.2",
+ "@types/react": "^18.3.23",
+ "@types/react-dom": "^18.3.7",
+ "@vitejs/plugin-react": "^4.5.2",
+ "typescript": "5.4.5",
+ "vite": "^5.4.19"
+ }
+}
diff --git a/examples/react/grid/src/index.css b/examples/react/grid/src/index.css
@@ -0,0 +1,77 @@
+*,
+*:before,
+*:after {
+ box-sizing: border-box;
+}
+
+html {
+ font-family: sans-serif;
+ font-size: 14px;
+}
+
+body {
+ padding: 1rem;
+}
+
+.List {
+ border: 1px solid #e6e4dc;
+ max-width: 100%;
+}
+
+.ListItemEven,
+.ListItemOdd {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+}
+
+.ListItemEven {
+ background-color: #e6e4dc;
+}
+
+.controls {
+ display: flex;
+ gap: 0.5rem;
+ margin-bottom: 1rem;
+ flex-wrap: wrap;
+ align-items: center;
+}
+
+.controls label {
+ display: flex;
+ align-items: center;
+ gap: 0.25rem;
+ cursor: pointer;
+}
+
+.mode-selector {
+ display: flex;
+ gap: 0.5rem;
+ padding: 0.5rem;
+ background: #f5f5f5;
+ border-radius: 4px;
+}
+
+.mode-selector label {
+ padding: 0.25rem 0.5rem;
+ border-radius: 4px;
+}
+
+.mode-selector input:checked + span {
+ background: #007bff;
+ color: white;
+ padding: 0.25rem 0.5rem;
+ border-radius: 4px;
+ margin: -0.25rem -0.5rem;
+}
+
+button {
+ border: 1px solid gray;
+ padding: 0.25rem 0.5rem;
+ background: white;
+ cursor: pointer;
+}
+
+button:hover {
+ background: #f0f0f0;
+}
diff --git a/examples/react/grid/src/main.tsx b/examples/react/grid/src/main.tsx
@@ -0,0 +1,261 @@
+import * as React from 'react'
+import { createRoot } from 'react-dom/client'
+import { faker } from '@faker-js/faker'
+import { useVirtualizer } from '@tanstack/react-virtual'
+
+import './index.css'
+
+type SizingMode = 'dynamic' | 'fixed' | 'variable'
+
+const randomNumber = (min: number, max: number) =>
+ faker.number.int({ min, max })
+
+const rowCount = 10000
+const columnCount = 10000
+
+// Generate cell content for dynamic mode
+const generateCellContent = (row: number, col: number) => {
+ // Use a deterministic seed based on position
+ faker.seed(row * columnCount + col)
+ return faker.lorem.words(randomNumber(1, 4))
+}
+
+// Pre-computed variable sizes for "variable" mode
+const variableRowHeights = new Array(rowCount)
+ .fill(true)
+ .map(() => 25 + Math.round(Math.random() * 75))
+
+const variableColumnWidths = new Array(columnCount)
+ .fill(true)
+ .map(() => 75 + Math.round(Math.random() * 125))
+
+function Grid() {
+ const parentRef = React.useRef<HTMLDivElement>(null)
+ const [sizingMode, setSizingMode] = React.useState<SizingMode>('dynamic')
+
+ // Row virtualizer
+ const rowVirtualizer = useVirtualizer({
+ count: rowCount,
+ getScrollElement: () => parentRef.current,
+ estimateSize: React.useCallback(
+ (index: number) => {
+ switch (sizingMode) {
+ case 'fixed':
+ return 35
+ case 'variable':
+ return variableRowHeights[index]
+ case 'dynamic':
+ default:
+ return 50
+ }
+ },
+ [sizingMode],
+ ),
+ overscan: 5,
+ })
+
+ // Column virtualizer
+ const columnVirtualizer = useVirtualizer({
+ horizontal: true,
+ count: columnCount,
+ getScrollElement: () => parentRef.current,
+ estimateSize: React.useCallback(
+ (index: number) => {
+ switch (sizingMode) {
+ case 'fixed':
+ return 100
+ case 'variable':
+ return variableColumnWidths[index]
+ case 'dynamic':
+ default:
+ return 120
+ }
+ },
+ [sizingMode],
-estimateSize: React.useCallback(
-(index: number)=>{
-switch(sizingMode){
-case'fixed':
-return100
-case'variable':
-returnvariableColumnWidths[index]
-case'dynamic':
- default:
-return120
-}
-},
-[sizingMode],
+estimateSize: (index: number)=>{
+switch(sizingMode){
+case'fixed':
+return100
+case'variable':
+returnvariableColumnWidths[index]
+case'dynamic':
+ default:
+return120
+}
+},
+getItemKey: React.useCallback((index: number)=>index,[sizingMode]),
-estimateSize: React.useCallback(
-(index: number)=>{
-switch(sizingMode){
-case'fixed':
-return100
-case'variable':
-returnvariableColumnWidths[index]
-case'dynamic':
- default:
-return120
-}
-},
-[sizingMode],
+estimateSize: (index: number)=>{
+switch(sizingMode){
+case'fixed':
+return100
+case'variable':
+returnvariableColumnWidths[index]
+case'dynamic':
+ default:
+return120
+}
+},
+getItemKey: React.useCallback((index: number)=>index,[sizingMode]),
+ ),
+ overscan: 5,
+ })
+
+ const virtualRows = rowVirtualizer.getVirtualItems()
+ const virtualColumns = columnVirtualizer.getVirtualItems()
+
+ return (
+ <div>
+ <div className="controls">
+ <div className="mode-selector">
+ <strong>Sizing Mode:</strong>
+ {(['dynamic', 'fixed', 'variable'] as const).map((mode) => (
+ <label key={mode}>
+ <input
+ type="radio"
+ name="sizingMode"
+ value={mode}
+ checked={sizingMode === mode}
+ onChange={() => setSizingMode(mode)}
+ style={{ display: 'none' }}
+ />
+ <span>{mode.charAt(0).toUpperCase() + mode.slice(1)}</span>
+ </label>
+ ))}
+ </div>
+ </div>
+
+ <div className="controls">
+ <button
+ onClick={() => {
+ rowVirtualizer.scrollToIndex(0)
+ columnVirtualizer.scrollToIndex(0)
+ }}
+ >
+ Scroll to top-left
+ </button>
+ <button
+ onClick={() => {
+ rowVirtualizer.scrollToIndex(Math.floor(rowCount / 2))
+ columnVirtualizer.scrollToIndex(Math.floor(columnCount / 2))
+ }}
+ >
+ Scroll to center
+ </button>
+ <button
+ onClick={() => {
+ rowVirtualizer.scrollToIndex(rowCount - 1)
+ columnVirtualizer.scrollToIndex(columnCount - 1)
+ }}
+ >
+ Scroll to bottom-right
+ </button>
+ </div>
+
+ <p style={{ fontSize: '12px', color: '#666' }}>
+ {sizingMode === 'dynamic' && (
+ <>
+ <strong>Dynamic mode:</strong> Cell sizes are estimated and can vary
+ based on content. Best for unknown or variable content.
+ </>
+ )}
+ {sizingMode === 'fixed' && (
+ <>
+ <strong>Fixed mode:</strong> All cells have the same dimensions
+ (35px height, 100px width). Best performance for uniform grids.
+ </>
+ )}
+ {sizingMode === 'variable' && (
+ <>
+ <strong>Variable mode:</strong> Each row/column has pre-computed
+ dimensions. Use when sizes are known but vary per row/column.
+ </>
+ )}
+ </p>
+
+ <div
+ ref={parentRef}
+ className="List"
+ style={{
+ height: 500,
+ width: '100%',
+ maxWidth: 800,
+ overflow: 'auto',
+ contain: 'strict',
-height: 500,
-width: '100%',
-maxWidth: 800,
-overflow: 'auto',
-contain: 'strict',
+height: 500,
+width: '100%',
+maxWidth: 800,
+overflow: 'auto',
+contain: 'strict',
+overflowAnchor: 'none',
-height: 500,
-width: '100%',
-maxWidth: 800,
-overflow: 'auto',
-contain: 'strict',
+height: 500,
+width: '100%',
+maxWidth: 800,
+overflow: 'auto',
+contain: 'strict',
+overflowAnchor: 'none',
+ }}
+ >
+ <div
+ style={{
+ height: rowVirtualizer.getTotalSize(),
+ width: columnVirtualizer.getTotalSize(),
+ position: 'relative',
+ }}
+ >
+ {virtualRows.map((virtualRow) => (
+ <React.Fragment key={virtualRow.key}>
+ {virtualColumns.map((virtualColumn) => {
+ const isEven =
+ (virtualRow.index + virtualColumn.index) % 2 === 0
+ return (
+ <div
+ key={virtualColumn.key}
+ className={isEven ? 'ListItemEven' : 'ListItemOdd'}
+ style={{
+ position: 'absolute',
+ top: 0,
+ left: 0,
+ width:
+ sizingMode === 'fixed'
+ ? 100
+ : sizingMode === 'variable'
+ ? variableColumnWidths[virtualColumn.index]
+ : virtualColumn.size,
+ height:
+ sizingMode === 'fixed'
+ ? 35
+ : sizingMode === 'variable'
+ ? variableRowHeights[virtualRow.index]
+ : virtualRow.size,
+ transform: `translateX(${virtualColumn.start}px) translateY(${virtualRow.start}px)`,
+ padding: '4px',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ fontSize: '12px',
+ }}
+ >
+ {sizingMode === 'dynamic' ? (
+ <div>
+ <div style={{ fontWeight: 'bold', fontSize: '10px' }}>
+ {virtualRow.index},{virtualColumn.index}
+ </div>
+ <div style={{ fontSize: '11px' }}>
+ {generateCellContent(
+ virtualRow.index,
+ virtualColumn.index,
+ )}
+ </div>
+ </div>
+ ) : (
+ `${virtualRow.index}, ${virtualColumn.index}`
+ )}
+ </div>
+ )
+ })}
+ </React.Fragment>
+ ))}
+ </div>
+ </div>
+
+ <p style={{ marginTop: '1rem', fontSize: '12px', color: '#666' }}>
+ Rendering {virtualRows.length * virtualColumns.length} of{' '}
+ {(rowCount * columnCount).toLocaleString()} cells (
+ {virtualRows.length} rows x {virtualColumns.length} columns)
+ </p>
+ </div>
+ )
+}
+
+function App() {
+ return (
+ <div>
+ <h1>Grid Virtualization</h1>
+ <p>
+ Efficiently render large 2D grids (spreadsheets, data tables, game
+ boards) by only rendering visible cells. Both rows and columns are
+ virtualized simultaneously.
+ </p>
+ <Grid />
+ {process.env.NODE_ENV === 'development' && (
+ <p style={{ marginTop: '2rem', fontSize: '12px', color: '#999' }}>
+ <strong>Note:</strong> Running in development mode. Performance will
+ improve in production builds.
+ </p>
+ )}
+ </div>
+ )
+}
+
+const container = document.getElementById('root')!
+const root = createRoot(container)
+
+root.render(
+ <React.StrictMode>
+ <App />
+ </React.StrictMode>,
+)