TanStack · FatahChan · May 3, 2025 · May 3, 2025 · May 3, 2025 · May 5, 2025
diff --git a/examples/react/lanes/.gitignore b/examples/react/lanes/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
diff --git a/examples/react/lanes/README.md b/examples/react/lanes/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm run start` or `yarn start`
diff --git a/examples/react/lanes/index.html b/examples/react/lanes/index.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/lanes/package.json b/examples/react/lanes/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "tanstack-react-virtual-example-lanes",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "serve": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-pacer": "^0.2.0",
+    "@tanstack/react-virtual": "^3.13.6",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.6",
+    "@types/react": "^18.3.20",
+    "@types/react-dom": "^18.3.6",
+    "@vitejs/plugin-react": "^4.4.1",
+    "typescript": "5.2.2",
+    "vite": "^5.4.18"
+  }
+}
diff --git a/examples/react/lanes/src/index.css b/examples/react/lanes/src/index.css
@@ -0,0 +1,28 @@
+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;
+}
+
+button {
+  border: 1px solid gray;
+}
diff --git a/examples/react/lanes/src/main.tsx b/examples/react/lanes/src/main.tsx
@@ -0,0 +1,271 @@
+import * as React from 'react'
+import * as ReactDOM from 'react-dom/client'
+
+import './index.css'
+
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { debounce } from '@tanstack/react-pacer'
+
+function App() {
+  return (
+    <div>
+      <p>
+        <strong>Lanes</strong> are useful when you are trying to draw a grid of items, where
+        each row is split into multiple columns.
+      </p>
+      <br />
+      <br />
+
+      <h3>Lanes</h3>
+      <LanesGapVirtualizer  />
+      <br />
+      <br />
+      <h3>Lanes Gaps</h3>
+      <GapVirtualizer />
+      <br />
+      <br />
+      <h3>Resizable Container Lanes</h3>
+      <ResizeVirtualizer />
+      <br />
+      <br />
+      <br />
+      <br />
+      {process.env.NODE_ENV === 'development' ? (
+        <p>
+          <strong>Notice:</strong> You are currently running React in
+          development mode. Rendering performance will be slightly degraded
+          until this application is built for production.
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+function LanesGapVirtualizer() {
+  const [numLanes, setNumLanes] = React.useState(4)
+  const parentRef = React.useRef(null)
+
+  const rowVirtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+    overscan: 5,
+    lanes: numLanes,
+  })
+
+  return (
+    <>
+      <div style={{ display: 'grid', gridTemplateColumns: '80px 200px', gap: '10px' }}>
+        <label htmlFor="numLanes1">Num Lanes</label>
+        <input type="number" id="numLanes1" value={numLanes} onChange={(e) => {setNumLanes(Number(e.target.value)); rowVirtualizer.measure()}} />
+      </div>
+      <br />
+      <div
+        ref={parentRef}
+        className="List"
+        style={{
+          height: "200px",
+          width: "400px",
+          overflow: "auto",
+        }}
+      >
+        <div
+          style={{
+            height: `${rowVirtualizer.getTotalSize()}px`,
+            width: '100%',
+            position: 'relative',
+          }}
+        >
+          {rowVirtualizer.getVirtualItems().map((virtualRow) => (
+            <div
+              key={virtualRow.index}
+              className={virtualRow.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
+              style={{
+                position: 'absolute',
+                top: 0,
+                left: `calc(${virtualRow.index % numLanes} * 100% / ${numLanes})`,
+                width: `calc(100% / ${numLanes})`,
+                height: `${virtualRow.size}px`,
+                transform: `translateY(${virtualRow.start}px)`,
+              }}
+            >
+              Cell {virtualRow.index}
+            </div>
+          ))}
+        </div>
+      </div>
+    </>
+  )
+}
+
+function GapVirtualizer() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+  const [numLanes, setNumLanes] = React.useState(4)
+  const [rowGap, setRowGap] = React.useState(10)
+  const [columnGap, setColumnGap] = React.useState(10)
+
+  const rowVirtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+    overscan: 5,
+    lanes: numLanes,
+    gap: rowGap,
+  })
+
+  return (
+    <>
+      <div style={{ display: 'grid', gridTemplateColumns: '80px 200px', gap: '10px' }}>
+        <label htmlFor="numLanes2">Num Lanes</label>
+        <input type="number" id="numLanes2" value={numLanes} onChange={(e) => {setNumLanes(Number(e.target.value)); rowVirtualizer.measure()}} />
+        <label htmlFor="rowGap" >Row Gap</label>
+        <input type="number" id="rowGap" value={rowGap} onChange={(e) => {setRowGap(Number(e.target.value)); rowVirtualizer.measure()}} />
+        <label htmlFor="columnGap">Column Gap</label>
+        <input type="number" id="columnGap" value={columnGap} onChange={(e) => {setColumnGap(Number(e.target.value)); rowVirtualizer.measure()}} />
+      </div>
+      <br />
+
+      <div
+        ref={parentRef}
+        className="List"
+        style={{
+          height: "200px",
+          width: "400px",
+          overflow: "auto",
+        }}
+      >
+        <div
+          style={{
+            height: `${rowVirtualizer.getTotalSize()}px`,
+            width: '100%',
+            position: 'relative',
+          }}
+        >
+          {rowVirtualizer.getVirtualItems().map((virtualRow) => {
+            return (
+            <div
+              key={virtualRow.index}
+              className={virtualRow.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
+              style={{
+                position: 'absolute',
+                top: 0,
+                "--start-ratio": `calc(mod(${virtualRow.index}, ${numLanes}) / ${numLanes})`,
+                left: `calc((var(--start-ratio) * 100%) + (${columnGap}px * var(--start-ratio)))`,
+                height: `${virtualRow.size}px`,
+                transform: `translateY(${virtualRow.start}px)`,
+                outline: '1px solid red',
+              } as React.CSSProperties}
+            >
+              Cell {virtualRow.index}
+            </div>
+            )
+          })}
+        </div>
+      </div>
+    </>
+  )
+}
+
+const CELL_WIDTH = 100
+function ResizeVirtualizer() {
+  const parentRef = React.useRef<HTMLDivElement>(null)
+  const [numLanes, setNumLanes] = React.useState(4)
+  const [rowGap, setRowGap] = React.useState(10)
+  const [columnGap, setColumnGap] = React.useState(10)
+
+  const rowVirtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+    overscan: 5,
+    lanes: numLanes,
+    gap: rowGap,
+  })
+
+  React.useEffect(() => {
+     if (!parentRef.current) return
+     // debounce not necessary
+     const debouncedOnResize = debounce((entries:  Array<ResizeObserverEntry>) => {
+      const rect = entries.at(0)?.contentRect
+      if (!rect) return
+      const { width } = rect
+      setNumLanes(Math.floor(width / CELL_WIDTH))
+      rowVirtualizer.measure()
+     }, {
+      wait: 50,
+
+     })
+     const resizeObserver = new ResizeObserver((entries) => {
+       debouncedOnResize(entries)
+     })
+     resizeObserver.observe(parentRef.current)
+     return () => {
+       resizeObserver.disconnect()
+     }
+  }, [rowVirtualizer])
+
+
+
+  return (
+    <>
+    <div style={{ display: 'grid', gridTemplateColumns: '80px 200px', gap: '10px' }}>
+      <label htmlFor="numLanes2">Num Lanes</label>
+      <input type="number" id="numLanes2" value={numLanes}  readOnly disabled/>
+      <label htmlFor="rowGap" >Row Gap</label>
+      <input type="number" id="rowGap" value={rowGap} onChange={(e) => {setRowGap(Number(e.target.value)); rowVirtualizer.measure()}} />
+      <label htmlFor="columnGap">Column Gap</label>
+      <input type="number" id="columnGap" value={columnGap} onChange={(e) => {setColumnGap(Number(e.target.value)); rowVirtualizer.measure()}} />
+    </div>
+    <br />
+
+    <div
+      ref={parentRef}
+      className="List"
+      style={{
+        height: "200px",
+        width: "400px",
+        overflow: "auto",
+        minWidth: CELL_WIDTH,
+        minHeight: "35px",
+        resize: 'horizontal',
+      }}
+    >
+      <div
+        style={{
+          height: `${rowVirtualizer.getTotalSize()}px`,
+          width: '100%',
+          position: 'relative',
+        }}
+      >
+        {rowVirtualizer.getVirtualItems().map((virtualRow) => {
+          return (
+          <div
+            key={virtualRow.index}
+            className={virtualRow.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
+            style={{
+              position: 'absolute',
+              top: 0,
+              "--start-ratio": `calc(mod(${virtualRow.index}, ${numLanes}) / ${numLanes})`,
+              left: `calc((var(--start-ratio) * 100%) + (${columnGap}px * var(--start-ratio)))`,
+              width: `calc((100% / ${numLanes}) - (${columnGap}px * (${numLanes} - 1) / ${numLanes}))`,
+              height: `${virtualRow.size}px`,
+              transform: `translateY(${virtualRow.start}px)`,
+              outline: '1px solid red',
+            } as React.CSSProperties}
+          >
+            Cell {virtualRow.index}
+          </div>
+          )
+        })}
+      </div>
+    </div>
+    </>
+  )
+}
+
+// eslint-disable-next-line
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
diff --git a/examples/react/lanes/tsconfig.json b/examples/react/lanes/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "composite": true,
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
diff --git a/examples/react/lanes/vite.config.js b/examples/react/lanes/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})