Vue Virtual Scroller
Developmentvue-virtual-scrollerVue Virtual Scroller is an Agent Skill for development published in the Akryum/vue-virtual-scroller repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Akryum/vue-virtual-scroller/blob/HEAD/packages/vue-virtual-scroller/skills/vue-virtual-scroller/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/vue-virtual-scroller, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Vue Virtual Scroller
Use this skill when a task involves large Vue lists, DOM reuse, windowed rendering, or choosing between RecycleScroller, DynamicScroller, WindowScroller, and the headless helpers.
Quick choice
| 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. |
Setup
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)
Workflow
- Decide whether sizes are known before render.
- If sizes are fixed or already stored in data, start with
RecycleScrolleroruseRecycleScroller. - If sizes are unknown until the DOM renders, use
DynamicScrolleroruseDynamicScroller. - If the page owns scrolling, prefer
WindowScrolleroruseWindowScroller. - Set explicit scroll sizing, item sizing, and keying before debugging performance.
Sizing rules
- The scrolling surface must have real dimensions. Inner-scroll paths need a sized container plus overflow.
RecycleScrollersupports fixed numericitemSize,itemSize: nullwithsizeField, or anitemSize(item, index)resolver.DynamicScrolleranduseDynamicScrollerrequireminItemSizefor initial layout.gridItemsonly works with fixed numericitemSize.- Horizontal lists follow the same rules, but sizing applies on width instead of height.
flowModeis a vertical single-axis native-flow path. Use spacer elements fromstartSpacerSizeandendSpacerSizeinstead of an absolutely positioned inner wrapper.
Practical guidance
Fixed-size vs unknown-size
- Prefer
RecycleScrollerfor tables, simple rows, grids, and card lists where size is stable or already known in memory. - Use
DynamicScrollerfor message feeds, cards, or rows whose rendered content changes height after filtering, editing, or streaming. - Use headless helpers when the bundled wrapper markup gets in the way of semantics or design-system constraints.
Component vs headless
- Stay on component APIs when the default slot structure already fits the UI.
- Move to
useRecycleScrollerfor custom markup with known sizes. - Move to
useDynamicScrollerfor wrapper-free measurement, especially semantic tables and custom row shells. - Move to
useWindowScrollerwhen page scrolling is intentional and wrapper control still matters.
Rendering pitfalls
- Reused views mean child components must react when
itemchanges; do not assume a fresh instance per row. - Render from
pool, notvisiblePool, on headless paths when you want normal recycling behavior. - Only reach for
watchDatawhen a legacy no-ResizeObserverfallback matters. - On headless dynamic paths, render from
view.item. Reach forview.itemWithSizeonly when you need measured metadata. - Key nested images, but do not add unnecessary keys to the immediate recycled content.
Performance guardrails
emitUpdate,emitResize, andwatchDataadd work; keep them off unless the UI needs them.- Variable-size mode in
RecycleScrolleris heavier than fixed-size mode. DynamicScrolleris heavier than fixed-size virtualization, so use it only when measurement is necessary.- Browsers still impose large-element limits, so extremely large lists can hit practical ceilings.
Common layouts
- Chat feeds and append-heavy timelines map well to
DynamicScrolleroruseDynamicScroller. - Multi-column card galleries map to
RecycleScrollergrid mode. - Page-level search results or article feeds map to
WindowScrolleroruseWindowScroller. - Semantic tables map to
useDynamicScrolleroruseRecycleScrollerwithflowMode, plususeTableColumnWidthsto lock columns after measurement. - Custom design-system row components map to the headless helpers.
Scope limits
This skill intentionally focuses on documented public surfaces:
- setup and installation
RecycleScrollerDynamicScrollerDynamicScrollerItemWindowScrolleruseRecycleScrolleruseDynamicScrolleruseWindowScrolleruseTableColumnWidths
Do not infer undocumented behavior for these exported surfaces without updating docs first:
useIdStateuseDynamicScrollerItem- plugin install options beyond the documented setup path
References
| 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 |
Further reading
- references/installation-and-setup.md
- references/recycle-scroller.md
- references/dynamic-scroller.md
- references/dynamic-scroller-item.md
- references/window-scroller.md
- references/use-recycle-scroller.md
- references/use-dynamic-scroller.md
- references/use-window-scroller.md
- references/use-table-column-widths.md