Getting Started

vue-virtual-scroller helps you render large lists in Vue without paying the cost of mounting every item at once.

If you are new to the package, start here, then explore the demos or the video demo when you want to see the behavior in motion.

If you are upgrading from the latest release, read the v2 to v3 migration guide.

If you need Vue 2 support, use the v1 branch.

Installation

npm install vue-virtual-scroller

yarn add vue-virtual-scroller

pnpm add vue-virtual-scroller

Setup

vue-virtual-scroller ships ESM only and requires Vue 3.3+ for the generic component typing surface. Use it from an ESM-aware toolchain such as Vite, Nuxt, Rollup, or webpack 5.

TypeScript generics

With Vue 3.3+, the component APIs infer the item type from the items prop, so scoped slot props such as item stay typed without extra annotations.

The headless composables also expose explicit generics when you want stronger type checking for returned state and helpers:

const recycleScroller = useRecycleScroller<User>(options, scrollerEl)
const dynamicScroller = useDynamicScroller<Message>(options)
const windowScroller = useWindowScroller<Row>(options, rootEl)

For object items, the composables validate string keyField values and variable-size sizeField values against the declared item type. You can also pass a keyField function with the signature (item, index) => string | number when you need a derived or composite key.

Plugin import

Install all components:

import VueVirtualScroller from 'vue-virtual-scroller'

app.use(VueVirtualScroller)

Or register only the components you need:

import { RecycleScroller } from 'vue-virtual-scroller'

app.component('RecycleScroller', RecycleScroller)

WARNING

Make sure to import the package CSS:

import 'vue-virtual-scroller/index.css'

Components

vue-virtual-scroller includes the following components:

• RecycleScroller — the main component for lists with known item sizes or sizes already stored in your data.

• DynamicScroller — builds on RecycleScroller and measures items as they render when size is not known in advance.

• DynamicScrollerItem — the measurement wrapper used inside DynamicScroller.

• WindowScroller — a window-based version of the API for lists that should follow page scrolling instead of an inner container.

Headless APIs

Use the headless APIs when you want the virtualization engine without the bundled component markup. This is ideal for <table> elements or highly custom layouts.

• Start with useRecycleScroller when item size is fixed or already known.
• Move to useDynamicScroller when the DOM needs to measure size after render.
• Use useWindowScroller when the page should still drive scrolling, but you need custom wrappers or semantics.

Utilities

• Use useTableColumnWidths when semantic table columns should stay stable while row content churns.