Use this skill for Vue 3 virtual scrolling with vue-virtual-scroller, important for good performance with a lot of data, including RecycleScroller, DynamicScroller, DynamicScrollerItem, WindowScroller, useRecycleScroller, useDynamicScroller, and useWindowScroller for fixed-size lists, unknown-size rows, grids, chat feeds, tables, and page-scrolling layouts.
Use this skill when a task involves large Vue lists, DOM reuse, windowed rendering, or choosing between RecycleScroller, DynamicScroller, WindowScroller, and the headless helpers.
| Surface | Use it when | Avoid it when |
|---|---|---|
RecycleScroller | Item size is fixed, precomputed, or available from a numeric field or resolver. | The DOM must measure unknown item size after render. |
DynamicScroller | Item size is unknown before render and should be measured automatically. | A fixed-size or pre-sized path already works. |
DynamicScrollerItem | You are rendering children inside DynamicScroller and the wrapper fits the markup. | You need wrapper-free semantics such as table rows. |
WindowScroller | The browser window should drive scrolling for the component path. | The list should own its own scroll container. |
useRecycleScroller | You need the virtualization engine with custom markup for known-size or pre-sized items. | The slot-based components already fit the UI. |
useDynamicScroller | You need wrapper-free unknown-size measurement with custom markup or semantic table rows. | DynamicScroller plus DynamicScrollerItem already fits the UI. |
useWindowScroller | The page should keep scrolling, but you still need headless control over markup and wrappers. | An inner scroll container is acceptable. |
vue-virtual-scroller targets Vue 3, ships ESM only, and requires Vue 3.3+ for the generic component typing surface. Use it with an ESM-aware toolchain such as Vite, Nuxt, Rollup, or webpack 5.
pnpm add vue-virtual-scroller
Always import the package CSS:
import 'vue-virtual-scroller/index.css'
Install all bundled components:
import { createApp } from 'vue'
import VueVirtualScroller from 'vue-virtual-scroller'
const app = createApp(App)
app.use(VueVirtualScroller)
Or register/import only what you need:
import { RecycleScroller, WindowScroller } from 'vue-virtual-scroller'
app.component('RecycleScroller', RecycleScroller)
app.component('WindowScroller', WindowScroller)
RecycleScroller or useRecycleScroller.DynamicScroller or useDynamicScroller.WindowScroller or useWindowScroller.RecycleScroller supports fixed numeric itemSize, itemSize: null with sizeField, or an itemSize(item, index) resolver.DynamicScroller and useDynamicScroller require minItemSize for initial layout.gridItems only works with fixed numeric itemSize.flowMode is a vertical single-axis native-flow path. Use spacer elements from startSpacerSize and endSpacerSize instead of an absolutely positioned inner wrapper.RecycleScroller for tables, simple rows, grids, and card lists where size is stable or already known in memory.DynamicScroller for message feeds, cards, or rows whose rendered content changes height after filtering, editing, or streaming.useRecycleScroller for custom markup with known sizes.useDynamicScroller for wrapper-free measurement, especially semantic tables and custom row shells.useWindowScroller when page scrolling is intentional and wrapper control still matters.item changes; do not assume a fresh instance per row.pool, not visiblePool, on headless paths when you want normal recycling behavior.sizeDependencies over deep watchData.view.item. Reach for view.itemWithSize only when you need measured metadata.emitUpdate, emitResize, and watchData add work; keep them off unless the UI needs them.RecycleScroller is heavier than fixed-size mode.DynamicScroller is heavier than fixed-size virtualization, so use it only when measurement is necessary.DynamicScroller or useDynamicScroller.RecycleScroller grid mode.WindowScroller or useWindowScroller.useDynamicScroller or useRecycleScroller with flowMode, plus useTableColumnWidths to lock columns after measurement.This skill intentionally focuses on documented public surfaces:
RecycleScrollerDynamicScrollerDynamicScrollerItemWindowScrolleruseRecycleScrolleruseDynamicScrolleruseWindowScrolleruseTableColumnWidthsDo not infer undocumented behavior for these exported surfaces without updating docs first:
useIdStateuseDynamicScrollerItem| Topic | Description | Reference |
|---|---|---|
| Installation and setup | Vue 3.3+, ESM-only setup, CSS import, and registration paths. | references/installation-and-setup.md |
| RecycleScroller | Fixed-size and pre-sized virtualization, grids, cache restore, and older page mode. | references/recycle-scroller.md |
| DynamicScroller | Unknown-size component path that measures items after render. | references/dynamic-scroller.md |
| DynamicScrollerItem | Measurement wrapper used inside DynamicScroller. | references/dynamic-scroller-item.md |
| WindowScroller | Window-based component path for page scrolling. | references/window-scroller.md |
| useRecycleScroller | Headless fixed-size and pre-sized virtualization. | references/use-recycle-scroller.md |
| useDynamicScroller | Headless unknown-size virtualization with wrapper-free measurement. | references/use-dynamic-scroller.md |
| useWindowScroller | Headless window-based virtualization. | references/use-window-scroller.md |
| useTableColumnWidths | Semantic table helper that locks measured column widths. | references/use-table-column-widths.md |
| Reference index | Overview of all shipped references. | references/index.md |