Skip to main content
skill CX Codex

tanstack-vue-virtual-skilld — Claude Code skill: features and setup

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.

MIT 129 installs ★ 186 updated 2026-10-10

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

What tanstack-vue-virtual-skilld does

The guide explains how the Vue adapter exposes useVirtualizer and useWindowVirtualizer, handles reactive options, and provides virtual items for rendering. It includes patterns for dynamic row heights and browser-window scrolling, plus details on Virtualizer methods and end-anchored feeds.

Its examples target @tanstack/vue-virtual 3.13.x with @tanstack/virtual-core 3.17.x. useVirtualizer requires count, getScrollElement, and estimateSize. The adapter supplies the scroll observers and scrollToFn itself, so passing those options can conflict with its setup. Check existing configuration before copying it across.

What it helps with

  • virtualize a long Vue list
  • build a virtualized grid
  • debug reactive useVirtualizer options
  • keep measurements while a list is hidden
  • anchor a chat feed to its end

Example prompts for the agent

  • Set up dynamic-height Vue rows with @tanstack/vue-virtual and explain how to measure them.
  • Review my useWindowVirtualizer setup and account for the list's page offset.
  • Show how to anchor this chat feed to the end using @tanstack/virtual-core 3.17.x.

How to install tanstack-vue-virtual-skilld

1Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-virtual-skilld -a claude-code

2Manually: put the files in place

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

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

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

Questions about tanstack-vue-virtual-skilld

How do I install tanstack-vue-virtual-skilld in Claude Code?

Run npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-virtual-skilld -a claude-code. The skill file is at ~/.claude/skills/tanstack-vue-virtual-skilld/SKILL.md.

What does tanstack-vue-virtual-skilld do?

It helps implement and debug virtualized Vue lists, grids, and feeds. The guide covers adapter behavior, rendering patterns, scrolling, and item measurement.

Which options does useVirtualizer require?

It requires count, getScrollElement, and estimateSize. The adapter supplies observeElementRect, observeElementOffset, and scrollToFn, so do not pass those yourself.

Source text

SKILL.md · MIT
---
name: tanstack-vue-virtual-skilld
description: Headless UI for virtualizing scrollable elements in Vue. Use when writing, reviewing, or debugging code that imports @tanstack/vue-virtual, calls useVirtualizer or useWindowVirtualizer, or virtualizes lists, grids, masonry, window-scrolled content, or chat feeds in Vue. Provides version-accurate adapter rules, Virtualizer options and methods, and rendering recipes for @tanstack/vue-virtual 3.13.x on @tanstack/virtual-core 3.17.x.
license: MIT
---

# @tanstack/vue-virtual

Headless list/grid virtualization for Vue. The adapter is thin: `useVirtualizer` and `useWindowVirtualizer` construct a core `Virtualizer`, wire it to Vue reactivity, and return it as a `Ref`. Every option and method below comes from `@tanstack/virtual-core`, which the adapter re-exports (`src/index.ts:21`).

## Version facts

- Target: `@tanstack/[email protected]` (`package.json:3`).
- Exact dependency: `@tanstack/[email protected]` (`package.json:52`).
- Peer: `vue ^2.7.0 || ^3.0.0` (`package.json:59`).
- The adapter API has been stable across 3.13.x; releases 3.13.25 to 3.13.39 only bump virtual-core ([vue-virtual changelog](https://github.com/TanStack/virtual/blob/main/packages/vue-virtual/CHANGELOG.md)).
- Install: `npm install @tanstack/vue-virtual` ([installation docs](https://tanstack.com/virtual/latest/docs/installation)).

## Quick start: dynamic-height rows

Canonical pattern, following the [official Vue dynamic example](https://github.com/TanStack/virtual/blob/main/examples/vue/dynamic/src/components/RowVirtualizerDynamic.vue). Block translation positions the rendered block by the first item's `start`; each item flows normally inside it.

```vue
<script setup lang="ts">
import { computed, onMounted, onUpdated, ref, shallowRef } from 'vue'
import { useVirtualizer } from '@tanstack/vue-virtual'

const parentRef = ref<HTMLElement | null>(null)
const rows = Array.from({ length: 10000 }, (_, i) => `Row ${i}`)

const rowVirtualizer = useVirtualizer({
  count: rows.length,
  getScrollElement: () => parentRef.value,
  estimateSize: () => 55,
  overscan: 5,
})

const virtualRows = computed(() => rowVirtualizer.value.getVirtualItems())
const totalSize = computed(() => rowVirtualizer.value.getTotalSize())

const itemEls = shallowRef<HTMLElement[]>([])
function measureAll() {
  rowVirtualizer.value.measureElement(null) // prune disconnected nodes
  itemEls.value.forEach((el) => el && rowVirtualizer.value.measureElement(el))
}
onMounted(measureAll)
onUpdated(measureAll)
</script>

<template>
  <div ref="parentRef" style="height: 400px; overflow-y: auto; contain: strict">
    <div :style="{ height: `${totalSize}px`, position: 'relative', width: '100%' }">
      <div
        :style="{
          position: 'absolute',
          top: 0,
          left: 0,
          width: '100%',
          transform: `translateY(${virtualRows[0]?.start ?? 0}px)`,
        }"
      >
        <div
          v-for="virtualRow in virtualRows"
          :key="virtualRow.key"
          :data-index="virtualRow.index"
          ref="itemEls"
        >
          {{ rows[virtualRow.index] }}
        </div>
      </div>
    </div>
  </div>
</template>
```

The scroll container needs a bounded height and `overflow: auto`. The inner sizer div carries `getTotalSize()`.

## Window virtualizer

`useWindowVirtualizer` scrolls with the browser window; it pre-fills `getScrollElement` (SSR-safe) and `initialOffset`, so pass neither ([vue-virtual docs](https://tanstack.com/virtual/latest/docs/framework/vue/vue-virtual), `src/index.ts:104-114`). When the list sits below other content, measure that offset into `scrollMargin`:

```ts
const parentOffset = ref(0)
onMounted(() => {
  parentOffset.value = parentRef.value?.offsetTop ?? 0
})

const rowVirtualizer = useWindowVirtualizer(
  computed(() => ({
    count: rows.length,
    estimateSize: () => 45,
    scrollMargin: parentOffset.value,
  })),
)
```

Pattern source: [official window example](https://github.com/TanStack/virtual/blob/main/examples/vue/dynamic/src/components/RowVirtualizerDynamicWindow.vue).

## Vue adapter rules (proven by `src/index.ts`)

- Returns `Ref<Virtualizer>`, not a raw instance. Use `.value` in script; templates auto-unwrap (`src/index.ts:30,69`).
- Options accept `MaybeRef`. A plain object is applied once; to update `count`, `overscan`, `enabled`, etc. reactively, pass a `ref` or `computed` of the whole options object. The adapter watches `() => unref(options)` and calls `setOptions` on change (`src/index.ts:48-65`).
- `getScrollElement()` is watched with `immediate: true`. A template ref that is still `null` on setup is picked up when it mounts (`src/index.ts:36-46`).
- `onChange` is wrapped: the adapter calls `triggerRef` on its internal `shallowRef` before your callback, so `computed(() => rowVirtualizer.value.getVirtualItems())` re-evaluates on scroll and resize (`src/index.ts:53-56`).
- Observers are cleaned up via `onScopeDispose` (`src/index.ts:67`).
- Items measured with `measureElement` must carry the index attribute, `data-index` by default (configurable via `indexAttribute`).
- Do not pass `observeElementRect`, `observeElementOffset`, or `scrollToFn`; the adapter pre-fills them (`src/index.ts:83-90`).

Details: [Vue adapter API](./references/vue-adapter.md).

## API reference

Full options table, instance methods, and `VirtualItem` shape: [Virtualizer API](./references/virtualizer-api.md).

Required options for `useVirtualizer`: `count`, `getScrollElement`, `estimateSize` ([virtualizer docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)).

## What is new since virtual-core 3.14.0

vue-virtual 3.13.39 ships core 3.17.11; these arrived via core minors ([virtual-core changelog](https://github.com/TanStack/virtual/blob/main/packages/virtual-core/CHANGELOG.md)):

- 3.16.0: end-anchored mode for chat, logs, reverse feeds. `anchorTo: 'end'`, `followOnAppend`, `scrollEndThreshold`, plus `scrollToEnd()`, `isAtEnd()`, `getDistanceFromEnd()`. See [Chat and end anchoring](./references/chat-end-anchoring.md).
- 3.15.0: `takeSnapshot()` for scroll restoration round-trips with `initialMeasurementsCache` + `initialOffset`.
- 3.15.0: default scroll adjustment now skips compensation during backward scroll (fixes "items jump while scrolling up"); override by assigning the instance property `shouldAdjustScrollPositionOnItemSizeChange`, which is not an option.
- 3.15.0: iOS Safari momentum-scroll handling, default on; scroll compensation writes are deferred while touching or bouncing.
- 3.17.0: `useCachedMeasurements` keeps measurements alive while the list is hidden.
- Pre-3.15 options still current: `lanes` with `laneAssignmentMode` (3.14.0), `gap`, `indexAttribute`, `initialMeasurementsCache`, `isRtl`.

## Best practices

- Estimate large for dynamic items: set `estimateSize` near the maximum likely size so initial positions and the scrollbar stay stable ([virtualizer docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)).
- Prefer block translation (as in the quick start) over per-item absolute positioning; smooth `scrollToIndex` skips measuring items far from the target, and block translation keeps the rendered block internally consistent ([virtualizer docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)).
- Give a stable `getItemKey` (row id, not index) whenever data reorders, filters, prepends, or streams; index keys break end-anchored chat and scroll restoration ([chat docs](https://tanstack.com/virtual/latest/docs/chat)).
- Subtract `scrollMargin` from item starts when items are positioned absolutely inside a shared scroll container ([virtualizer docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)).
- Use the `gap` option instead of CSS margins so `getTotalSize()` accounts for spacing.
- `count` changes invalidate the measurement cache and update `getTotalSize()` automatically (fixed in 3.13.13, [changelog](https://github.com/TanStack/virtual/blob/main/packages/vue-virtual/CHANGELOG.md)); in Vue still route reactive data through `computed` options.
- Leave `useAnimationFrameWithResizeObserver` off unless measured to help; it defers measurements by a frame ([virtualizer docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)).
- Pause observers with `enabled: false` instead of unmounting to preserve measurements.

Recipes for masonry, padding, sticky headers, scroll restoration, and hidden lists: [Patterns](./references/patterns.md).

Migrating from v2: `useVirtual` is gone; v3 uses `useVirtualizer`, the `count` option (not `size`), `getScrollElement` (not `parentRef`), and `measureElement` refs with `data-index` ([vue-virtual docs](https://tanstack.com/virtual/latest/docs/framework/vue/vue-virtual)).

## References

- [Vue adapter API](./references/vue-adapter.md): signatures, reactivity contract, SSR behavior.
- [Virtualizer API](./references/virtualizer-api.md): all options, defaults, instance methods, `VirtualItem`.
- [Patterns](./references/patterns.md): masonry, scroll margin, sticky ranges, scroll restoration, hidden lists.
- [Chat and end anchoring](./references/chat-end-anchoring.md): `anchorTo: 'end'` chat feeds in Vue.

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

Similar skills

All skills for Frontend and UI →

From the same set32

The whole set →
vueuse-integrations-skilld vueuse-integrations-skilld equips AI agents with reference rules for 12 utility wrappers in @vueuse/integrations v15. Prevents broken imports and guides API migration. CX Codex +1 145installs tanstack-vue-table-skilld tanstack-vue-table-skilld helps AI agents write and migrate @tanstack/vue-table v9 code. Enforces explicit tableFeatures, atom-based state, and clean Vue 3 reactivity patterns. CX Codex +1 144installs vueuse-motion-skilld vueuse-motion-skilld guides coding agents through @vueuse/motion v3 APIs in Vue 3 and Nuxt 3, preventing runtime bugs with SSR, timing units, and imports. CX Codex +1 141installs vueuse-shared-skilld vueuse-shared-skilld — a skill that brings @vueuse/shared v15.0.0 API reference into Claude Code, Cursor, and other editors. Covers reactive utilities: debounce, throttle, watch variants, state sharing, and ref synchronization for Vue 3. CX Codex +1 137installs tanstack-vue-form-skilld tanstack-vue-form-skilld guides agents through writing, reviewing, and debugging Vue forms built with @tanstack/vue-form and its current API. CX Codex +1 125installs vueuse-math-skilld vueuse-math-skilld — a skill for @vueuse/math composables in Vue 3: clamp, project, round, and aggregate reactive numbers. CX Codex +1 119installs floating-ui-vue-skilld floating-ui-vue-skilld guides AI coding agents on anchoring tooltips, popovers, and menus using @floating-ui/vue 2.0.1 in Vue 3.3+. CX Codex +1 119installs vue-data-ui-skilld The vue-data-ui-skilld skill guides agents working with the vue-data-ui Vue 3 chart library, from component selection and theming to SSR and debugging. CX Codex +1 118installs

Project sponsors

Companies that keep this analytics open