Skip to main content
skill CX Codex

tanstack-virtual · oakoss — Claude Code skill: what it does, how to install

A skill that teaches the agent to virtualize long lists, grids and tables with TanStack Virtual, so only visible rows stay in the DOM.

MIT 148 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tanstack-virtual -a claude-code
Open on GitHub

What tanstack-virtual does

Inside the skill the agent gets a pattern sheet for TanStack Virtual, a headless utility that keeps only on-screen items mounted. Vertical and horizontal lists, a grid built from two virtualizer instances sharing one scroll element, dynamic heights through measureElement, window scrolling, scrollToIndex, lanes and overscan are each mapped to their API call.

The mistakes section carries the weight. A scroll parent without overflow: auto and a fixed height will not scroll at all, and the inner sizing container has to be position: relative. Dynamic measurement also needs data-index on every item. Under React Compiler, components using useVirtualizer need the 'use no memo' directive.

Four reference files go deeper: lists, grids, dynamic sizing, and infinite scroll wired to TanStack Query. Table work and data fetching are handed to the tanstack-table and tanstack-query skills when those are installed. Lists under ~100 items gain nothing from virtualization.

What it helps with

  • virtualize a table with thousands of rows without flooding the DOM
  • wire infinite scroll on top of TanStack Query
  • stop the scroll position from jumping with variable row heights
  • pin sticky headers with a custom rangeExtractor
  • swap absolute positioning for translateY to keep scrolling smooth

Example prompts for the agent

  • This list of 5000 rows is lagging. Move it to useVirtualizer and overestimate the row height.
  • Build a virtualized grid with separate row and column virtualizers over one scroll container.
  • Add infinite scroll to the table and page the data through TanStack Query.

How to install tanstack-virtual

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-virtual -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-virtual/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-virtual/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-virtual

How do I install tanstack-virtual in Claude Code?

Run npx skills add oakoss/agent-skills --skill tanstack-virtual -a claude-code, then the skill file lands at ~/.claude/skills/tanstack-virtual/SKILL.md.

What does tanstack-virtual do?

It gives the agent TanStack Virtual patterns for lists, grids and tables, and tells it which options to pass into useVirtualizer.

What has to be in place for virtualization to work?

The scroll parent needs overflow: auto and a fixed height, and the inner container sized by getTotalSize() needs position: relative. With dynamic measurement every item also carries data-index.

Source text

SKILL.md · MIT
---
name: tanstack-virtual
description: 'TanStack Virtual for virtualizing large lists, grids, and tables. Use when rendering thousands of rows, implementing infinite scroll, or optimizing large data displays. Use for virtual, virtualize, virtual-list, virtual-scroll, useVirtualizer, infinite-scroll, windowing.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: 'https://tanstack.com/virtual/latest'
user-invocable: false
---

# TanStack Virtual

## Overview

TanStack Virtual is a headless UI utility for virtualizing large lists, grids, and tables. It renders only the visible items in the viewport, dramatically reducing DOM nodes and improving performance for datasets with thousands of rows. Framework adapters are available for React, Vue, Solid, Svelte, Lit, and Angular.

**When to use:** Rendering thousands of rows or columns, building virtualized tables, implementing infinite scroll, displaying large datasets where DOM node count impacts performance.

**When NOT to use:** Small lists under ~100 items (no performance benefit), server-rendered static content, layouts where all items must be in the DOM for SEO or accessibility, simple pagination (render one page at a time instead).

## Quick Reference

| Pattern             | API                                                         | Key Points                                               |
| ------------------- | ----------------------------------------------------------- | -------------------------------------------------------- |
| Vertical list       | `useVirtualizer({ count, getScrollElement, estimateSize })` | Wrap items in absolute-positioned container              |
| Horizontal list     | `useVirtualizer({ horizontal: true, ... })`                 | Use `getTotalSize()` for width instead of height         |
| Grid layout         | Row virtualizer + column virtualizer                        | Two virtualizer instances sharing one scroll element     |
| Dynamic sizing      | `ref={virtualizer.measureElement}`                          | Set `data-index` on each element                         |
| Window scroller     | `useWindowVirtualizer({ count, estimateSize })`             | No `getScrollElement` needed                             |
| Scroll to item      | `virtualizer.scrollToIndex(index)`                          | Supports `align: 'start' \| 'center' \| 'end' \| 'auto'` |
| Scroll to offset    | `virtualizer.scrollToOffset(px)`                            | Supports `align` and `behavior: 'smooth'`                |
| Custom keys         | `getItemKey: (index) => items[index].id`                    | Stable keys improve measurement cache                    |
| Overscan            | `overscan: 5`                                               | Renders extra items outside viewport (default: 1)        |
| Gap between items   | `gap: 8`                                                    | Space between virtualized items in pixels                |
| Multi-lane layout   | `lanes: 3`                                                  | Masonry-style column layouts                             |
| Padding             | `paddingStart: 100, paddingEnd: 100`                        | Space before first and after last item                   |
| RTL support         | `isRtl: true`                                               | Right-to-left horizontal scrolling                       |
| Range extractor     | `rangeExtractor: (range) => [...]`                          | Customize rendered indices (sticky headers, footers)     |
| Disable virtualizer | `enabled: false`                                            | Renders nothing, resets internal state                   |
| Force remeasure     | `virtualizer.measure()`                                     | Call after external layout changes                       |

## Common Mistakes

| Mistake                                             | Correct Pattern                                                                                             |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Missing `overflow: auto` on scroll container        | Parent element must have `overflow: auto` and a fixed height/width                                          |
| Using `virtualItem.index` as React key              | Use `virtualItem.key` which accounts for dynamic reordering                                                 |
| Forgetting `position: relative` on inner container  | The total-size container must be `position: relative`                                                       |
| Not setting `data-index` with `measureElement`      | Dynamic measurement requires `data-index={virtualItem.index}` on each element                               |
| Setting `estimateSize` too small for dynamic items  | Overestimate to prevent scroll jumping; use largest expected size                                           |
| Recreating `getScrollElement` on every render       | Use a ref callback: `() => parentRef.current`                                                               |
| Not using `getTotalSize()` for container dimensions | Inner container height/width must equal `virtualizer.getTotalSize()`                                        |
| Absolute positioning without `transform`            | Use `transform: translateY(item.start)` for GPU-accelerated positioning                                     |
| Using `contain: strict` without fixed dimensions    | `contain: strict` requires explicit width and height on the scroll container                                |
| Using with React Compiler without opting out        | Add `'use no memo'` directive to components using `useVirtualizer` — interior mutability breaks memoization |

## Delegation

> If the `tanstack-table` skill is available, delegate data table virtualization to it. TanStack Table has built-in virtualization integration.
> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill tanstack-table`
>
> If the `tanstack-query` skill is available, delegate data fetching and infinite query patterns to it.
> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill tanstack-query`

## References

- [List virtualization with useVirtualizer](references/list-virtualization.md)
- [Grid virtualization with row and column virtualizers](references/grid-virtualization.md)
- [Dynamic sizing with measureElement](references/dynamic-sizing.md)
- [Infinite scroll with TanStack Query integration](references/infinite-scroll.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

tanstack-virtual by other authors comes first.

tanstack-virtual tanstack-skills Shows the agent how to wire up TanStack Virtual so only visible rows render in long lists, tables and grids. CX Codex +1 2,600installs tanstack-vue-virtual-skilld skilld-dev The tanstack-vue-virtual-skilld skill guides Vue work with @tanstack/vue-virtual, from implementing virtual lists to debugging adapter usage. It also covers window scrolling and chat feeds anchored at the end. CX Codex +1 129installs virtual-lists patterns.dev virtual-lists teaches your coding agent list virtualization and windowing techniques for React. Solves scroll stutter and reduces initial rendering time for heavy datasets. CX Codex +1 1,700installs tanstack-integration-best-practices DeckardGer tanstack-integration-best-practices — a skill that hands the agent rules for wiring TanStack Query, Router and Start together: loaders, SSR hydration, cache ownership. Useful once all three live in one codebase. CX Codex +1 3,100installs clerk-tanstack-patterns clerk The clerk-tanstack-patterns Claude Code skill covers Clerk authentication patterns for TanStack React Start. It activates for work with createServerFn, beforeLoad route protection, and request middleware. CX Codex +1 16,400installs tanstack-start tanstack-skills Guides agents through building full-stack React apps with TanStack Start, streaming SSR, and type-safe server functions. CX Codex +1 4,000installs tanstack-pacer tanstack-skills tanstack-pacer is a Claude Code skill for choosing utilities that control when functions run. It comes into play for debouncing, rate limits, queues, and batching. CX Codex +1 3,900installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open