TanStack Virtual

https://tanstack.com/virtual/latest/docs
Admin
TanStack Virtual is a headless UI library designed for efficiently rendering large lists and tables...
Tokens:33,659
Snippets:222
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install Marko Virtual

Source: https://tanstack.com/virtual/latest/docs/installation.md

Install the Marko-specific adapter for TanStack Virtual.

```bash
npm install @tanstack/marko-virtual
```

--------------------------------

### Install Virtual Core

Source: https://tanstack.com/virtual/latest/docs/installation.md

Install the framework-agnostic core package for TanStack Virtual.

```bash
npm install @tanstack/virtual-core
```

--------------------------------

### Variable Size Virtualization Example

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/variable

A comprehensive example showing row, column, grid, and masonry virtualization with variable element sizes.

```typescript
import React from 'react'
import * as ReactDOM from 'react-dom/client'

import './index.css'

import { useVirtualizer } from '@tanstack/react-virtual'

const rows = new Array(10000)
  .fill(true)
  .map(() => 25 + Math.round(Math.random() * 100))

const columns = new Array(10000)
  .fill(true)
  .map(() => 75 + Math.round(Math.random() * 100))

function App() {
  return (
    <div>
      <p>
        These components are using <strong>variable</strong> sizes. This means
        that each element has a unique, but knowable dimension at render time.
      </p>
      <br />
      <br />

      <h3>Rows</h3>
      <RowVirtualizerVariable rows={rows} />
      <br />
      <br />
      <h3>Columns</h3>
      <ColumnVirtualizerVariable columns={columns} />
      <br />
      <br />
      <h3>Grid</h3>
      <GridVirtualizerVariable rows={rows} columns={columns} />
      <br />
      <br />
      <h3>Masonry (vertical)</h3>
      <MasonryVerticalVirtualizerVariable rows={rows} />
      <br />
      <br />
      <h3>Masonry (horizontal)</h3>
      <MasonryHorizontalVirtualizerVariable rows={rows} />
      <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 RowVirtualizerVariable({ rows }: { rows: Array<number> }) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (i) => rows[i],
    overscan: 5,
  })

  return (
    <>
      <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: 0,
                width: '100%',
                height: `${rows[virtualRow.index]}px`,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              Row {virtualRow.index}
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

function ColumnVirtualizerVariable({ columns }: { columns: Array<number> }) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: columns.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (i) => columns[i],
    overscan: 5,
  })

  return (
    <>
      <div
        ref={parentRef}
        className="List"
        style={{
          width: `400px`,
          height: `100px`,
          overflow: 'auto',
        }}
      >
        <div
          style={{
            width: `${columnVirtualizer.getTotalSize()}px`,
            height: '100%',
            position: 'relative',
          }}
        >
          {columnVirtualizer.getVirtualItems().map((virtualColumn) => (
            <div
              key={virtualColumn.index}
              className={
                virtualColumn.index % 2 ? 'ListItemOdd' : 'ListItemEven'
              }
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                height: '100%',
                width: `${columns[virtualColumn.index]}px`,
                transform: `translateX(${virtualColumn.start}px)`,
              }}
            >
              Column {virtualColumn.index}
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

function GridVirtualizerVariable({
  rows,
  columns,
}: {
  rows: Array<number>
  columns: Array<number>
}) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (i) => rows[i],
    overscan: 5,
  })
```

--------------------------------

### Install Pretext with npm

Source: https://tanstack.com/virtual/latest/docs/pretext.md

Install the @chenglou/pretext package to use text measurement and layout in your project.

```sh
npm install @chenglou/pretext
```

--------------------------------

### App Routing and Initialization

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/dynamic

The main App component handles routing between different virtualization examples and initializes the React root.

```jsx
function App() {
  const pathname = location.pathname
  return (
    <div>
      <p>
        These components are using <strong>dynamic</strong> sizes. This means
        that each element's exact dimensions are unknown when rendered. An
        estimated dimension is used as the initial measurement, then this
        measurement is readjusted on the fly as each element is rendered.
      </p>
      <nav>
        <ul>
          <li>
            <a href="/">List</a>
          </li>
          <li>
            <a href="/columns">Column</a>
          </li>
          <li>
            <a href="/grid">Grid</a>
          </li>
          <li>
            <a href="/experimental">Experimental</a>
          </li>
        </ul>
      </nav>
      {(() => {
        switch (pathname) {
          case '/':
            return <RowVirtualizerDynamic />
          case '/columns':
            return <ColumnVirtualizerDynamic />
          case '/grid': {
            const columns = generateColumns(30)
            const data = generateData(columns)
            return <GridVirtualizerDynamic columns={columns} data={data} />
          }
          case '/experimental':
            return <RowVirtualizerExperimental />
          default:
            return <div>Not found</div>
        }
      })()}
      <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>
  )
}

const container = document.getElementById('root')!
const root = createRoot(container)
const { StrictMode } = React

root.render(
  <StrictMode>
    <App />
  </StrictMode>,
)
```

--------------------------------

### Implementing Padding in Virtualized Lists and Grids

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/padding

This example demonstrates how to configure padding for row, column, and grid virtualizers using the useVirtualizer hook. It includes dynamic sizing where element dimensions are estimated and then measured on the fly.

```tsx
import React from 'react'
import * as ReactDOM from 'react-dom/client'

import './index.css'

import { useVirtualizer } from '@tanstack/react-virtual'

const rows = new Array(10000)
  .fill(true)
  .map(() => 25 + Math.round(Math.random() * 100))

const columns = new Array(10000)
  .fill(true)
  .map(() => 75 + Math.round(Math.random() * 100))

function App() {
  return (
    <div>
      <p>
        These components are using <strong>dynamic</strong> sizes. This means
        that each element's exact dimensions are unknown when rendered. An
        estimated dimension is used as the initial measurement, then this
        measurement is readjusted on the fly as each element is rendered.
      </p>
      <br />
      <br />

      <h3>Rows</h3>
      <RowVirtualizerDynamic rows={rows} />
      <br />
      <br />
      <h3>Columns</h3>
      <ColumnVirtualizerDynamic columns={columns} />
      <br />
      <br />
      <h3>Grid</h3>
      <GridVirtualizerDynamic rows={rows} columns={columns} />
    </div>
  )
}

function RowVirtualizerDynamic({ rows }: { rows: Array<number> }) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    paddingStart: 100,
    paddingEnd: 100,
  })

  return (
    <>
      <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.key}
              data-index={virtualRow.index}
              ref={rowVirtualizer.measureElement}
              className={virtualRow.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                width: '100%',
                height: `${rows[virtualRow.index]}px`,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              Row {virtualRow.index}
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

function ColumnVirtualizerDynamic({ columns }: { columns: Array<number> }) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: columns.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    paddingStart: 100,
    paddingEnd: 100,
  })

  return (
    <>
      <div
        ref={parentRef}
        className="List"
        style={{
          width: `400px`,
          height: `100px`,
          overflow: 'auto',
        }}
      >
        <div
          style={{
            width: `${columnVirtualizer.getTotalSize()}px`,
            height: '100%',
            position: 'relative',
          }}
        >
          {columnVirtualizer.getVirtualItems().map((virtualColumn) => (
            <div
              key={virtualColumn.key}
              data-index={virtualColumn.index}
              ref={columnVirtualizer.measureElement}
              className={
                virtualColumn.index % 2 ? 'ListItemOdd' : 'ListItemEven'
              }
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                height: '100%',
                width: `${columns[virtualColumn.index]}px`,
                transform: `translateX(${virtualColumn.start}px)`,
              }}
            >
              Column {virtualColumn.index}
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

function GridVirtualizerDynamic({
  rows,
  columns,
}: {
  rows: Array<number>
  columns: Array<number>
}) {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    paddingStart: 200,
    paddingEnd: 200,
    indexAttribute: 'data-row-index',
  })
```

--------------------------------

### Row and Column Dynamic Virtualization

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/dynamic

Examples demonstrating row-based and column-based dynamic virtualization using the useVirtualizer hook with measureElement.

```typescript
import * as React from 'react'
import { createRoot } from 'react-dom/client'
import { faker } from '@faker-js/faker'

import { useVirtualizer, useWindowVirtualizer } from '@tanstack/react-virtual'

import './index.css'

const randomNumber = (min: number, max: number) =>
  faker.number.int({ min, max })

const sentences = new Array(10000)
  .fill(true)
  .map(() => faker.lorem.sentence(randomNumber(20, 70)))

function RowVirtualizerDynamic() {
  const parentRef = React.useRef<HTMLDivElement>(null)

  const [enabled, setEnabled] = React.useState(true)

  const count = sentences.length
  const virtualizer = useVirtualizer({
    count,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 45,
    enabled,
    directDomUpdates: true,
  })

  React.useEffect(() => {
    virtualizer.scrollToIndex(count - 1, { align: 'end' })
  }, [])

  return (
    <div>
      <button
        onClick={() => {
          virtualizer.scrollToIndex(0)
        }}
      >
        scroll to the top
      </button>
      <span style={{ padding: '0 4px' }} />
      <button
        onClick={() => {
          virtualizer.scrollToIndex(count / 2, { behavior: 'smooth' })
        }}
      >
        scroll to the middle
      </button>
      <span style={{ padding: '0 4px' }} />
      <button
        onClick={() => {
          virtualizer.scrollToIndex(count - 1)
        }}
      >
        scroll to the end
      </button>
      <span style={{ padding: '0 4px' }} />
      <button
        onClick={() => {
          setEnabled((prev) => !prev)
        }}
      >
        turn {enabled ? 'off' : 'on'} virtualizer
      </button>
      <hr />
      <div
        ref={parentRef}
        className="List"
        style={{
          height: 400,
          width: 400,
          overflowY: 'auto',
          contain: 'strict',
          overflowAnchor: 'none',
        }}
      >
        <div
          ref={virtualizer.containerRef}
          style={{
            width: '100%',
            position: 'relative',
          }}
        >
          {virtualizer.getVirtualItems().map((v) => (
            <div
              key={v.key}
              data-testid={`item-${v.index}`}
              ref={virtualizer.measureElement}
              className={v.index % 2 ? 'ListItemOdd' : 'ListItemEven'}
              data-index={v.index}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                width: '100%',
              }}
            >
              <div style={{ padding: '10px 0' }}>
                <div>Row {v.index}</div>
                <div>{sentences[v.index]}</div>
              </div>
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}

function ColumnVirtualizerDynamic() {
  const parentRef = React.useRef<HTMLDivElement | null>(null)

  const virtualizer = useVirtualizer({
    horizontal: true,
    count: sentences.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 45,
  })

  return (
    <>
      <div
        ref={parentRef}
        className="List"
        style={{ width: 400, height: 400, overflowY: 'auto' }}
      >
        <div
          style={{
            width: virtualizer.getTotalSize(),
            height: '100%',
            position: 'relative',
          }}
        >
          {virtualizer.getVirtualItems().map((virtualColumn) => (
            <div
              key={virtualColumn.key}
              data-index={virtualColumn.index}
              ref={virtualizer.measureElement}
              className={
                virtualColumn.index % 2 ? 'ListItemOdd' : 'ListItemEven'
              }
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                height: '100%',
                transform: `translateX(${virtualColumn.start}px)`,
              }}
            >
              <div style={{ width: sentences[virtualColumn.index].length }}>
                <div>Column {virtualColumn.index}</div>
                <div>{sentences[virtualColumn.index]}</div>
              </div>
            </div>
          ))}
        </div>
      </div>
    </>
  )
}

interface Column {
  key: string
  name: string
  width: number
}

function GridVirtualizerDynamic({
  columns,
  data,
}: {
  data: Array<Array<string>>
  columns: Array<Column>
}) {
  const parentRef = React.useRef<HTMLDivElement | null>(null)

  const parentOffsetRef = React.useRef(0)
```

--------------------------------

### VirtualItem start Property

Source: https://tanstack.com/virtual/latest/docs/api/virtual-item.md

The starting pixel offset, typically used for CSS positioning like top, left, or transforms.

```tsx
start: number
```

--------------------------------

### Implement Fixed Size Virtualization in React

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/fixed

This example shows the main application structure for rendering fixed-size rows, columns, and grids using the useVirtualizer hook.

```typescript
import * as React from 'react'
import * as ReactDOM from 'react-dom/client'
  

import './index.css'
  

import { useVirtualizer } from '@tanstack/react-virtual'
  

function App() {
return (
<div>
<p>
These components are using <strong>fixed</strong> sizes. This means that
every element's dimensions are hard-coded to the same value and never
change.
</p>
<br />
<br />
  

<h3>Rows</h3>
<RowVirtualizerFixed />
<br />
<br />
<h3>Columns</h3>
<ColumnVirtualizerFixed />
<br />
<br />
<h3>Grid</h3>
<GridVirtualizerFixed />
<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>
```

--------------------------------

### directDomUpdatesMode example

Source: https://tanstack.com/virtual/latest/docs/framework/react/react-virtual.md

Example of using directDomUpdatesMode: 'position' to write top/left instead of transform. Requires item elements to be position: absolute.

```tsx
const virtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
  directDomUpdates: true,
  directDomUpdatesMode: 'position', // Use top/left instead of transform
})
```

--------------------------------

### Virtualized React Table Implementation

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/table

This snippet shows the setup for a virtualized table using useVirtualizer and useReactTable. It includes column definitions and state management for sorting.

```typescript
import * as React from 'react'
import { createRoot } from 'react-dom/client'
  

import { useVirtualizer } from '@tanstack/react-virtual'
import {
flexRender,
getCoreRowModel,
getSortedRowModel,
useReactTable,
} from '@tanstack/react-table'
import { makeData } from './makeData'
import type { ColumnDef, Row, SortingState } from '@tanstack/react-table'
import type { Person } from './makeData'
import './index.css'
  

function ReactTableVirtualized() {
const [sorting, setSorting] = React.useState<SortingState>([])
  

const columns = React.useMemo<Array<ColumnDef<Person>>>(
() => [
{
accessorKey: 'id',
header: 'ID',
size: 60,
},
{
accessorKey: 'firstName',
cell: (info) => info.getValue(),
},
{
accessorFn: (row) => row.lastName,
id: 'lastName',
cell: (info) => info.getValue(),
header: () => <span>Last Name</span>,
},
{
```

--------------------------------

### useFlushSync example

Source: https://tanstack.com/virtual/latest/docs/framework/react/react-virtual.md

Example of using useFlushSync: false to disable synchronous updates, which can eliminate React 19 console warnings and improve performance.

```tsx
const virtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
  useFlushSync: false, // Disable synchronous updates
})
```

--------------------------------

### directDomUpdates example

Source: https://tanstack.com/virtual/latest/docs/framework/react/react-virtual.md

Example of enabling directDomUpdates to skip React re-renders for scroll-only updates. Requires item elements to be position: absolute and the inner container to use virtualizer.containerRef without setting height/width.

```tsx
const virtualizer = useVirtualizer({
  count: 10000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
  directDomUpdates: true,
})

return (
  <div ref={parentRef} style={{ overflow: 'auto', height: 400 }}>
    {/* The inner container must use virtualizer.containerRef and not set height */}
    <div ref={virtualizer.containerRef} style={{ position: 'relative' }}>
      {virtualizer.getVirtualItems().map((item) => (
        <div
          key={item.key}
          ref={virtualizer.measureElement}
          data-index={item.index}
          style={{
            position: 'absolute',
            top: 0,
            left: 0,
            width: '100%',
            // Do NOT set top/left/transform — the virtualizer handles it
          }}
        >
          Row {item.index}
        </div>
      ))}
    </div>
  </div>
)
```

--------------------------------

### measureElement implementation

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Example of applying measureElement to a virtualized item element, ensuring the data-index attribute is present.

```tsx
 <div
  key={virtualRow.key}
  data-index={virtualRow.index}
  ref={virtualizer.measureElement}
  style={...}
>...</div>
```

--------------------------------

### Chat Component Implementation in main.tsx

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/chat

The main entry point for the chat example, importing necessary dependencies including TanStack Virtual and React Query to manage and render virtualized chat messages.

```typescript
import * as React from 'react'
import { createRoot } from 'react-dom/client'
import { QueryClientProvider } from '@tanstack/react-query'
import { useVirtualizer } from '@tanstack/react-virtual'
import { queryClient, useChats, useMessages, useSendMessage } from './queries'
import type { Message } from './api'
import './index.css'
  

// Feather icon paths (MIT, feathericons.com), 24×24 strokes.
const icons = {
menu: 'M3 6h18M3 12h18M3 18h18',
close: 'M15 18l-6-6 6-6',
newChat: 'M12 20h9M16.5 3.5a2.1 2.1 0 0 1 3 3L7 19l-4 1 1-4Z',
up: 'M12 19V5M5 12l7-7 7 7',
down: 'M12 5v14M19 12l-7 7-7-7',
stop: 'M7 7h10v10H7Z',
}
  

function Icon({ path }: { path: string }) {
return (
<svg
width="20"
height="20"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
strokeWidth="2"
strokeLinecap="round"
strokeLinejoin="round"
aria-hidden="true"
>
<path d={path} />
</svg>
)
}
```

--------------------------------

### Implement Smooth Scroll with scrollToFn

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/smooth-scroll

This example uses a custom scrollToFn to animate scrolling to specific indices or offsets within a virtualized list. It utilizes requestAnimationFrame and an easing function to handle the scroll transition.

```tsx
import React from 'react'
import * as ReactDOM from 'react-dom/client'

import './index.css'

import { elementScroll, useVirtualizer } from '@tanstack/react-virtual'
import type { VirtualizerOptions } from '@tanstack/react-virtual'

function easeInOutQuint(t: number) {
  return t < 0.5 ? 16 * t * t * t * t * t : 1 + 16 * --t * t * t * t * t
}

function App() {
  const parentRef = React.useRef<HTMLDivElement>(null)
  const scrollingRef = React.useRef<number>()

  const scrollToFn: VirtualizerOptions<any, any>['scrollToFn'] =
    React.useCallback((offset, canSmooth, instance) => {
      const duration = 1000
      const start = parentRef.current?.scrollTop || 0
      const startTime = (scrollingRef.current = Date.now())

      const run = () => {
        if (scrollingRef.current !== startTime) return
        const now = Date.now()
        const elapsed = now - startTime
        const progress = easeInOutQuint(Math.min(elapsed / duration, 1))
        const interpolated = start + (offset - start) * progress

        if (elapsed < duration) {
          elementScroll(interpolated, canSmooth, instance)
          requestAnimationFrame(run)
        } else {
          elementScroll(interpolated, canSmooth, instance)
        }
      }

      requestAnimationFrame(run)
    }, [])

  const rowVirtualizer = useVirtualizer({
    count: 10000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35,
    overscan: 5,
    scrollToFn,
  })

  const randomIndex = Math.floor(Math.random() * 10000)

  return (
    <div>
      <p>
        This smooth scroll example uses the <code>`scrollToFn`</code> to
        implement a custom scrolling function for the methods like{' '}
        <code>`scrollToIndex`</code> and <code>`scrollToOffset`</code>
      </p>

      <br />
      <br />

      <div>
        <button onClick={() => rowVirtualizer.scrollToIndex(randomIndex)}>
          Scroll To Random Index ({randomIndex})
        </button>
      </div>

      <br />
      <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: 0,
                width: '100%',
                height: `${virtualRow.size}px`,
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              Row {virtualRow.index}
            </div>
          ))}
        </div>
      </div>
      <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>
  )
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)
```

--------------------------------

### Configure useVirtualizer with padding

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/padding

Initializes the column virtualizer with paddingStart and paddingEnd properties to define spacing.

```javascript
  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: columns.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    paddingStart: 200,
    paddingEnd: 200,
    indexAttribute: 'data-column-index',
  })
```

--------------------------------

### cancelScroll

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Cancels an in-flight scrollToIndex, scrollToOffset, scrollBy or scrollToEnd. Useful when the user starts their own scroll.

```APIDOC
## cancelScroll

### Description
Cancels an in-flight `scrollToIndex`, `scrollToOffset`, `scrollBy` or `scrollToEnd`. After those calls, the virtualizer keeps correcting toward the target for a short time while items are measured. Call `cancelScroll` when the user starts their own scroll (for example from `wheel`, `touchstart` or `keydown` handlers) so the viewport stays where the user takes it. The current scroll position is not changed. It does nothing when no scroll is in flight.

### Method
Function call

### Signature
```tsx
cancelScroll: () => void
```
```

--------------------------------

### 2D Grid Virtualization with Variable Sizes

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/variable

A component demonstrating a 2D grid where both rows and columns have variable sizes using useVirtualizer.

```javascript
  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: columns.length,
    getScrollElement: () => parentRef.current,
    estimateSize: (i) => columns[i],
    overscan: 5,
  })

  return (
    <>
      <div
        ref={parentRef}
        className="List"
        style={{
          height: `400px`,
          width: `500px`,
          overflow: 'auto',
        }}
      >
        <div
          style={{
            height: `${rowVirtualizer.getTotalSize()}px`,
            width: `${columnVirtualizer.getTotalSize()}px`,
            position: 'relative',
          }}
        >
          {rowVirtualizer.getVirtualItems().map((virtualRow) => (
            <React.Fragment key={virtualRow.index}>
              {columnVirtualizer.getVirtualItems().map((virtualColumn) => (
                <div
                  key={virtualColumn.index}
                  className={
                    virtualColumn.index % 2
                      ? virtualRow.index % 2 === 0
                        ? 'ListItemOdd'
                        : 'ListItemEven'
                      : virtualRow.index % 2
                        ? 'ListItemOdd'
                        : 'ListItemEven'
                  }
                  style={{
                    position: 'absolute',
                    top: 0,
                    left: 0,
                    width: `${columns[virtualColumn.index]}px`,
                    height: `${rows[virtualRow.index]}px`,
                    transform: `translateX(${virtualColumn.start}px) translateY(${virtualRow.start}px)`,
                  }}
                >
                  Cell {virtualRow.index}, {virtualColumn.index}
                </div>
              ))}
            </React.Fragment>
          ))}
        </div>
      </div>
    </>
  )
}
```

--------------------------------

### anchorTo

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Controls which side of the scrollable content is treated as the stable anchor when list data changes. Default is 'start'.

```APIDOC
## anchorTo

### Description
Controls which side of the scrollable content should be treated as the stable anchor when list data changes.

### Type
'start' | 'end'

### Default
'start'

### Usage
- The default 'start' preserves TanStack Virtual's existing top/left anchored behavior.
- Set anchorTo: 'end' for chat, logs, and reverse/inverted feeds. In end-anchored mode, the virtualizer keeps the current visible item stable when older items are prepended, and keeps an end-pinned viewport pinned when the last item grows during streaming output.
- For prepend stability, use a stable getItemKey based on each item's persistent id. Index keys cannot distinguish prepends from appends after items shift.
```

--------------------------------

### Virtualizer Constructor

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Creates a new Virtualizer instance with the provided options. The constructor accepts a VirtualizerOptions object containing required and optional configuration.

```APIDOC
## Virtualizer Constructor

### Description
Creates a new Virtualizer instance with the provided options.

### Constructor
`new Virtualizer<TScrollElement, TItemElement>(options: VirtualizerOptions<TScrollElement, TItemElement>)`

### Parameters
#### options (VirtualizerOptions) - Required
- **count** (number) - Required - The total number of items to virtualize.
- **getScrollElement** (() => TScrollElement) - Required - A function that returns the scrollable element for the virtualizer. It may return null if the element is not available yet.
- **estimateSize** ((index: number) => number) - Required - This function is passed the index of each item and should return the actual size (or estimated size if you will be dynamically measuring items with `virtualItem.measureElement`) for each item. This measurement should return either the width or height depending on the orientation of your virtualizer.
- **enabled** (boolean) - Optional - Set to `false` to disable scrollElement observers and reset the virtualizer's state.
- **debug** (boolean) - Optional - Set to `true` to enable debug logs.
- **initialRect** (Rect) - Optional - The initial `Rect` of the scrollElement. This is mostly useful if you need to run the virtualizer in an SSR environment, otherwise the initialRect will be calculated on mount by the `observeElementRect` implementation.
- **onChange** ((instance: Virtualizer<TScrollElement, TItemElement>, sync: boolean) => void) - Optional - A callback function that fires when the virtualizer's internal state changes. It's passed the virtualizer instance and the sync parameter. The sync parameter indicates whether scrolling is currently in progress. It is `true` when scrolling is ongoing, and `false` when scrolling has stopped or other actions (such as resizing) are being performed.
- **overscan** (number) - Optional - The number of items to render above and below the visible area. Increasing this number will increase the amount of time it takes to render the virtualizer, but might decrease the likelihood of seeing slow-rendering blank items at the top and bottom of the virtualizer when scrolling. The default value is `1`. When `lanes` is greater than `1`, overscan counts whole rows of `lanes` items, so every lane renders the same number of extra items.
- **horizontal** (boolean) - Optional - Set this to `true` if your virtualizer is oriented horizontally.
- **paddingStart** (number) - Optional - The padding to apply to the start of the virtualizer in pixels.
- **paddingEnd** (number) - Optional - The padding to apply to the end of the virtualizer in pixels.
- **scrollPaddingStart** (number) - Optional - The padding to apply to the start of the virtualizer in pixels when scrolling to an element.
- **scrollPaddingEnd** (number) - Optional - The padding to apply to the end of the virtualizer in pixels when scrolling to an element.
- **initialOffset** (number | (() => number)) - Optional - The position where the list is scrolled to on render. This is useful if you are rendering the virtualizer in a SSR environment or are conditionally rendering the virtualizer.
- **getItemKey** ((index: number) => Key) - Optional - This function is passed the index of each item and should return a unique key for that item. The default functionality of this function is to return the index of the item, but you should override this when possible to return a unique identifier for each item across the entire set.

### Notes
- If you are dynamically measuring your elements, it's recommended to estimate the largest possible size (width/height, within comfort) of your items. This will help the virtualizer calculate more accurate initial positions.
- The virtualizer automatically invalidates its measurement cache when measurement-affecting options change, ensuring `getTotalSize()` and other measurements return fresh values. While the virtualizer intelligently tracks which options actually affect measurements, it's still better to memoize `getItemKey` (e.g., using `useCallback` in React) to avoid unnecessary recalculations.
```

--------------------------------

### scrollMargin configuration

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Specifies the space between the beginning of the scrolling element and the start of the list, useful for headers or multiple virtualizers.

```tsx
scrollMargin?: number
```

```tsx
transform: `translateY(${
   virtualRow.start - rowVirtualizer.options.scrollMargin
}px)`
```

--------------------------------

### Configure Follow on Append

Source: https://tanstack.com/virtual/latest/docs/chat.md

Enable viewport pinning to the end when new messages arrive.

```tsx
followOnAppend: true
```

--------------------------------

### scrollMargin

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

Option to specify where the scroll offset should originate, typically representing the space between the beginning of the scrolling element and the start of the list.

```APIDOC
## scrollMargin

### Description
With this option, you can specify where the scroll offset should originate. Typically, this value represents the space between the beginning of the scrolling element and the start of the list. This is especially useful in common scenarios such as when you have a header preceding a window virtualizer or when multiple virtualizers are utilized within a single scrolling element. If you are using absolute positioning of elements, you should take into account the `scrollMargin` in your CSS transform:
```tsx
transform: `translateY(${
   virtualRow.start - rowVirtualizer.options.scrollMargin
}px)` 
``` 
To dynamically measure value for `scrollMargin` you can use `getBoundingClientRect()` or ResizeObserver. This is helpful in scenarios when items above your virtual list might change their height.

### Signature
```tsx
scrollMargin?: number
```

### Value
- **number** - The scroll margin in pixels.
```

--------------------------------

### Basic Pretext integration with TanStack Virtual

Source: https://tanstack.com/virtual/latest/docs/pretext.md

Cache prepare() by text and style, run layout() for the current width, and reset measurements on width or font changes. Includes a ResizeObserver to track width and a font-ready effect to clear caches and re-measure.

```tsx
import { clearCache, layout, prepare } from '@chenglou/pretext'
import { useVirtualizer } from '@tanstack/react-virtual'

const font = '14px Arial'
const lineHeight = 20
const preparedCache = new Map<string, ReturnType<typeof prepare>>()

function getPrepared(row: { id: string; text: string }) {
  const key = `${row.id}:${font}:${row.text}`
  const cached = preparedCache.get(key)

  if (cached) {
    return cached
  }

  const prepared = prepare(row.text, font, {
    whiteSpace: 'pre-wrap',
    letterSpacing: 0,
  })
  preparedCache.set(key, prepared)
  return prepared
}

function estimateRowHeight(row: { id: string; text: string }, contentWidth: number) {
  const text = layout(getPrepared(row), contentWidth, lineHeight)
  const textHeight = Math.max(lineHeight, text.height)

  return textHeight + 24
}

function Messages({ rows }: { rows: Array<{ id: string; text: string }> }) {
  const parentRef = React.useRef<HTMLDivElement>(null)
  const [width, setWidth] = React.useState(640)

  React.useLayoutEffect(() => {
    const element = parentRef.current

    if (!element) {
      return
    }

    const update = () => setWidth(element.clientWidth)
    const observer = new ResizeObserver(update)

    update()
    observer.observe(element)

    return () => observer.disconnect()
  }, [])

  const virtualizer = useVirtualizer({
    count: rows.length,
    getItemKey: (index) => rows[index]!.id,
    getScrollElement: () => parentRef.current,
    estimateSize: (index) => estimateRowHeight(rows[index]!, width - 32),
  })

  React.useLayoutEffect(() => {
    virtualizer.measure()
  }, [virtualizer, width])

  React.useEffect(() => {
    document.fonts.ready.then(() => {
      preparedCache.clear()
      clearCache()
      virtualizer.measure()
    })
  }, [virtualizer])

  return <div ref={parentRef}>{/* render virtual rows */}</div>
}
```

--------------------------------

### Mount React application

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/padding

Standard ReactDOM entry point for rendering the App component.

```jsx
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)
```

--------------------------------

### initialMeasurementsCache

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

A previously-captured snapshot of measured item sizes (from takeSnapshot()) to seed the virtualizer with on mount. Default is an empty array.

```APIDOC
## initialMeasurementsCache

### Description
A previously-captured snapshot of measured item sizes (from takeSnapshot()) to seed the virtualizer with on mount.

### Type
Array<VirtualItem>

### Default
[]

### Usage
- Useful for restoring scroll position after navigation: persist the result of takeSnapshot() (plus the current scrollOffset) in your route state, then pass them back as initialMeasurementsCache and initialOffset to land users at the same position without re-measuring everything from scratch.
- Items not present in the cache fall back to estimateSize; items present have their measured size restored.
- The cache is consumed only once, on the first getMeasurements() call after mount.
```

--------------------------------

### scrollOffset

Source: https://tanstack.com/virtual/latest/docs/api/virtualizer.md

The scrollOffset option represents the current scroll position along the scrolling axis, measured in pixels from the start of the scrollable area.

```APIDOC
## scrollOffset

### Description
The scrollOffset option represents the current scroll position along the scrolling axis. It is measured in pixels from the starting point of the scrollable area.

### Type
number

### Details
- It is a position in the list's layout, and it stays consistent with getOffsetForIndex, the argument to scrollToOffset, and initialOffset.
- Restoring a saved value returns to the same layout position. That is the same item only while the items and sizes before it are unchanged; to restore across changes, pair it with takeSnapshot() and initialMeasurementsCache, or scroll to the item with scrollToIndex.
- While a scroll correction is held, getVirtualItems() and getTotalSize() describe what is rendered, shifted by the held amount so the rows on screen do not move, while scrollOffset keeps the layout position.
- The hold ends with a single write once the element can take it.
- Prefer getVirtualItems() positions over item.start - scrollOffset for where a row sits in the viewport, since that difference is off by the held amount for the length of the gesture or bounce.
```

--------------------------------

### Configure useVirtualizer for Chat

Source: https://tanstack.com/virtual/latest/docs/chat.md

Initialize the virtualizer with end-anchoring enabled to support chat-like behavior.

```tsx
const virtualizer = useVirtualizer({
  count: messages.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 72,
  getItemKey: (index) => messages[index]!.id,
  anchorTo: 'end',
  followOnAppend: true,
  scrollEndThreshold: 80,
  overscan: 6,
})
```

--------------------------------

### Dynamic Column and Row Virtualization

Source: https://tanstack.com/virtual/latest/docs/framework/react/examples/dynamic

Implements a virtualized grid with dynamic column widths and row heights using useWindowVirtualizer and useVirtualizer.

```typescript
  React.useLayoutEffect(() => {
    parentOffsetRef.current = parentRef.current?.offsetTop ?? 0
  }, [])

  const getColumnWidth = (index: number) => columns[index].width

  const virtualizer = useWindowVirtualizer({
    count: data.length,
    estimateSize: () => 350,
    overscan: 5,
    scrollMargin: parentOffsetRef.current,
  })

  const columnVirtualizer = useVirtualizer({
    horizontal: true,
    count: columns.length,
    getScrollElement: () => parentRef.current,
    estimateSize: getColumnWidth,
    overscan: 5,
  })
  const columnItems = columnVirtualizer.getVirtualItems()
  const [before, after] =
    columnItems.length > 0
      ? [
          columnItems[0].start,
          columnVirtualizer.getTotalSize() -
            columnItems[columnItems.length - 1].end,
        ]
      : [0, 0]

  return (
    <div
      ref={parentRef}
      style={{ overflowY: 'auto', border: '1px solid #c8c8c8' }}
    >
      <div
        style={{
          height: virtualizer.getTotalSize(),
          position: 'relative',
        }}
      >
        {virtualizer.getVirtualItems().map((row) => {
          return (
            <div
              key={row.key}
              data-index={row.index}
              ref={virtualizer.measureElement}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                transform: `translateY(${
                  row.start - virtualizer.options.scrollMargin
                }px)`,
                display: 'flex',
              }}
            >
              <div style={{ width: `${before}px` }} />
              {columnItems.map((column) => {
                return (
                  <div
                    key={column.key}
                    style={{
                      minHeight: row.index === 0 ? 50 : row.size,
                      width: getColumnWidth(column.index),
                      borderBottom: '1px solid #c8c8c8',
                      borderRight: '1px solid #c8c8c8',
                      padding: '7px 12px',
                    }}
                  >
                    {row.index === 0 ? (
                      <div>{columns[column.index].name}</div>
                    ) : (
                      <div>{data[row.index][column.index]}</div>
                    )}
                  </div>
                )
              })}
              <div style={{ width: `${after}px` }} />
            </div>
          )
        })}
      </div>
    </div>
  )
}
```
Tokens:
Raw