createVirtual
Virtual scrolling composable for efficiently rendering large lists by only rendering visible items.
Usage
The createVirtual composable efficiently renders large lists by only mounting visible items plus a small overscan buffer. Pass an array of items and configure the item height to get back sliced items, scroll handlers, and positioning values.
<script setup lang="ts">
import { createVirtual } from '@vuetify/v0'
import { shallowRef } from 'vue'
const items = shallowRef(
Array.from({ length: 10_000 }, (_, i) => `Item ${i + 1}`)
)
const { element, items: visible, offset, size, scroll, scrollTo } = createVirtual(items, {
itemHeight: 40,
})
</script>
<template>
<div ref="element" class="h-[300px] overflow-y-auto" @scroll="scroll">
<div :style="{ height: `${offset}px` }" />
<div v-for="item in visible" :key="item.index">
{{ item.raw }}
</div>
<div :style="{ height: `${size}px` }" />
</div>
</template>Architecture
The rendering pipeline transforms scroll events into visible item ranges:
Reactivity
| Property/Method | Reactive | Notes |
|---|---|---|
element | Ref, assign scroll container | |
items | Computed, visible items with index | |
offset | ShallowRef, readonly (top spacer height) | |
size | ShallowRef, readonly (bottom spacer height) | |
state | ShallowRef ('loading' | 'empty' | 'error' | 'ok') |
Source items The items ref passed to createVirtual() is watched for changes. When items change, the virtual scroller updates automatically.
Examples
10,000-Item Virtual List
A scrollable list of 10,000 items that only renders visible rows, with jump-to-index and add-items controls.
Functions
createVirtual
(items: Ref<readonly T[], readonly T[]>, _options?: VirtualOptions) => VirtualContext<T>Virtual scrolling composable for efficiently rendering large lists
createVirtualContext
(items: Ref<readonly T[], readonly T[]>, _options?: VirtualContextOptions) => ContextTrinity<VirtualContext<T>>Creates a virtual scrolling context with dependency injection support.
useVirtual
(namespace?: string) => VirtualContext<T>Returns the current virtual context from dependency injection.
Options
onStartReached
((distance: number) => void | Promise<void>) | undefinedThe callback to call when the start is reached.
onEndReached
((distance: number) => void | Promise<void>) | undefinedThe callback to call when the end is reached.
Properties
Methods
Benchmarks
Every operation is profiled across multiple dataset sizes to measure real-world throughput. Each benchmark is assigned a performance tier—good, fast, blazing, or slow—and groups are scored by averaging their individual results so you can spot bottlenecks at a glance. This transparency helps you make informed decisions about which patterns scale for your use case. Learn more in the benchmarks guide.