# Tanstack Virtual

> Headless UI for virtualizing large element lists at 60FPS in TS/JS, React, Vue, Solid, Svelte, Lit & Angular.

- **Type:** Skill
- **Install:** `agentstack add skill-tanstack-skills-tanstack-skills-tanstack-virtual`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tanstack-skills](https://agentstack.voostack.com/s/tanstack-skills)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tanstack-skills](https://github.com/tanstack-skills)
- **Source:** https://github.com/tanstack-skills/tanstack-skills/tree/main/plugins/tanstack-virtual/skills/tanstack-virtual

## Install

```sh
agentstack add skill-tanstack-skills-tanstack-skills-tanstack-virtual
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Overview

TanStack Virtual provides virtualization logic for rendering only visible items in large lists, grids, and tables. It calculates which items are in the viewport and positions them with absolute positioning, keeping DOM node count minimal regardless of dataset size.

**Package:** `@tanstack/react-virtual`
**Core:** `@tanstack/virtual-core` (framework-agnostic)

## Installation

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

## Core Pattern

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

function VirtualList() {
  const parentRef = useRef(null)

  const virtualizer = useVirtualizer({
    count: 10000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 35, // estimated row height in px
    overscan: 5,
  })

  return (
    
      
        {virtualizer.getVirtualItems().map((virtualItem) => (
          
            Row {virtualItem.index}
          
        ))}
      
    
  )
}
```

## Virtualizer Options

### Required

| Option | Type | Description |
|--------|------|-------------|
| `count` | `number` | Total number of items |
| `getScrollElement` | `() => Element \| null` | Returns scroll container |
| `estimateSize` | `(index) => number` | Estimated item size (overestimate recommended) |

### Optional

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `overscan` | `number` | `1` | Extra items rendered beyond viewport |
| `horizontal` | `boolean` | `false` | Horizontal virtualization |
| `gap` | `number` | `0` | Gap between items (px) |
| `lanes` | `number` | `1` | Number of lanes (masonry/grid) |
| `paddingStart` | `number` | `0` | Padding before first item |
| `paddingEnd` | `number` | `0` | Padding after last item |
| `scrollPaddingStart` | `number` | `0` | Offset for scrollTo positioning |
| `scrollPaddingEnd` | `number` | `0` | Offset for scrollTo positioning |
| `initialOffset` | `number` | `0` | Starting scroll position |
| `initialRect` | `Rect` | - | Initial dimensions (SSR) |
| `enabled` | `boolean` | `true` | Enable/disable |
| `getItemKey` | `(index) => Key` | `(i) => i` | Stable key for items |
| `rangeExtractor` | `(range) => number[]` | default | Custom visible indices |
| `scrollToFn` | `(offset, options, instance) => void` | default | Custom scroll behavior |
| `measureElement` | `(el, entry, instance) => number` | default | Custom measurement |
| `onChange` | `(instance, sync) => void` | - | State change callback |
| `isScrollingResetDelay` | `number` | `150` | Delay before scroll complete |

## Virtualizer API

```typescript
// Get visible items
virtualizer.getVirtualItems(): VirtualItem[]

// Get total scrollable size
virtualizer.getTotalSize(): number

// Scroll to specific index
virtualizer.scrollToIndex(index, { align: 'start' | 'center' | 'end' | 'auto', behavior: 'auto' | 'smooth' })

// Scroll to offset
virtualizer.scrollToOffset(offset, options)

// Force recalculation
virtualizer.measure()
```

## VirtualItem Properties

```typescript
interface VirtualItem {
  key: Key           // Unique key
  index: number      // Index in source data
  start: number      // Pixel offset (use for transform)
  end: number        // End pixel offset
  size: number       // Item dimension
  lane: number       // Lane index (multi-column)
}
```

## Dynamic/Variable Heights

Use `measureElement` ref for items with unknown heights:

```tsx
const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50, // overestimate
})

{virtualizer.getVirtualItems().map((virtualItem) => (
  
    {items[virtualItem.index].content}
  
))}
```

## Horizontal Virtualization

```tsx
const virtualizer = useVirtualizer({
  count: columns.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 100,
  horizontal: true,
})

// Use width for container, translateX for positioning

  {virtualizer.getVirtualItems().map((item) => (
    
      Column {item.index}
    
  ))}

```

## Grid Virtualization (Two Virtualizers)

```tsx
function VirtualGrid() {
  const parentRef = useRef(null)

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

  const columnVirtualizer = useVirtualizer({
    count: 10000,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 100,
    horizontal: true,
    overscan: 5,
  })

  return (
    
      
        {rowVirtualizer.getVirtualItems().map((virtualRow) => (
          
            {columnVirtualizer.getVirtualItems().map((virtualColumn) => (
              
                Cell {virtualRow.index},{virtualColumn.index}
              
            ))}
          
        ))}
      
    
  )
}
```

## Window Scrolling

```tsx
import { useWindowVirtualizer } from '@tanstack/react-virtual'

function WindowList() {
  const listRef = useRef(null)

  const virtualizer = useWindowVirtualizer({
    count: 10000,
    estimateSize: () => 45,
    overscan: 5,
    scrollMargin: listRef.current?.offsetTop ?? 0,
  })

  return (
    
      
        {virtualizer.getVirtualItems().map((item) => (
          
            Row {item.index}
          
        ))}
      
    
  )
}
```

## Infinite Scrolling

```tsx
import { useVirtualizer } from '@tanstack/react-virtual'
import { useInfiniteQuery } from '@tanstack/react-query'

function InfiniteList() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
    queryKey: ['items'],
    queryFn: ({ pageParam = 0 }) => fetchItems(pageParam),
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  })

  const allItems = data?.pages.flatMap((page) => page.items) ?? []

  const virtualizer = useVirtualizer({
    count: hasNextPage ? allItems.length + 1 : allItems.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
    overscan: 5,
  })

  useEffect(() => {
    const items = virtualizer.getVirtualItems()
    const lastItem = items[items.length - 1]
    if (lastItem && lastItem.index >= allItems.length - 1 && hasNextPage && !isFetchingNextPage) {
      fetchNextPage()
    }
  }, [virtualizer.getVirtualItems(), hasNextPage, isFetchingNextPage, allItems.length])

  // Render virtual items, show loader row for last item if loading
}
```

## Sticky Items

```tsx
import { defaultRangeExtractor, Range } from '@tanstack/react-virtual'

const stickyIndexes = [0, 10, 20, 30] // Header indices

const virtualizer = useVirtualizer({
  count: 1000,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
  rangeExtractor: useCallback((range: Range) => {
    const next = new Set([...stickyIndexes, ...defaultRangeExtractor(range)])
    return [...next].sort((a, b) => a - b)
  }, [stickyIndexes]),
})

// Render sticky items with position: sticky; top: 0; zIndex: 1
```

## Smooth Scrolling

```tsx
const virtualizer = useVirtualizer({
  scrollToFn: (offset, { behavior }, instance) => {
    if (behavior === 'smooth') {
      // Custom easing animation
      instance.scrollElement?.scrollTo({ top: offset, behavior: 'smooth' })
    } else {
      instance.scrollElement?.scrollTo({ top: offset })
    }
  },
})

// Usage
virtualizer.scrollToIndex(500, { align: 'center', behavior: 'smooth' })
```

## Best Practices

1. **Overestimate `estimateSize`** - prevents scroll jumps (items shrinking causes issues)
2. **Increase `overscan`** (3-5) to reduce blank flashing during fast scrolling
3. **Use `transform: translateY()`** over `top` for GPU-composited positioning
4. **Add `data-index` attribute** when using `measureElement` for dynamic sizing
5. **Don't set fixed height** on dynamically measured items
6. **Use `getItemKey`** for stable keys when items can reorder
7. **Use `gap` option** instead of margins (margins interfere with measurement)
8. **Use `paddingStart/End`** instead of CSS padding on the container
9. **Use `enabled: false`** to pause when the list is hidden
10. **Memoize callbacks** (`estimateSize`, `getItemKey`, `rangeExtractor`)
11. **Use `will-change: transform`** CSS on items for GPU acceleration

## Common Pitfalls

- Setting fixed height on dynamically measured items
- Using CSS margins instead of the `gap` option
- Forgetting `data-index` with `measureElement`
- Not providing `position: relative` on the inner container
- Underestimating `estimateSize` (causes scroll jumps)
- Setting `overscan` too low for fast scrolling (blank items)
- Forgetting to subtract `scrollMargin` from `translateY` in window scrolling
- Not memoizing the `estimateSize` function (causes re-renders)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tanstack-skills](https://github.com/tanstack-skills)
- **Source:** [tanstack-skills/tanstack-skills](https://github.com/tanstack-skills/tanstack-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tanstack-skills-tanstack-skills-tanstack-virtual
- Seller: https://agentstack.voostack.com/s/tanstack-skills
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.