useVirtual

Virtual scrolling composable for efficiently rendering large lists by only rendering visible items.

Copy Page as Markdown

Intermediate98.3% coverage Blazing FastJan 14, 2026

Usage

The useVirtual 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.

0 (rendered) / 10000

Architecture

The rendering pipeline transforms scroll events into visible item ranges:

API Reference

The following API details are for the useVirtual composable.

Functions

useVirtual

(items: Ref<readonly T[], readonly T[]>, _options?: VirtualOptions) => VirtualContext<T>

Virtual scrolling composable for efficiently rendering large lists

Options

itemHeight

string | number

The height of the item.

height

string | number

The height of the container.

overscan

number

The number of extra items to render.

direction

VirtualDirection

The direction of the scrolling.

anchor

VirtualAnchor

The anchor of the scrolling.

anchorSmooth

boolean

Whether to smooth the anchor position.

onStartReached

(distance: number) => void | Promise<void>

The callback to call when the start is reached.

onEndReached

(distance: number) => void | Promise<void>

The callback to call when the end is reached.

startThreshold

number

The threshold for the start.

endThreshold

number

The threshold for the end.

momentum

boolean

Whether to enable momentum scrolling.

elastic

boolean

Whether to enable elastic scrolling.

Properties

element

Ref<HTMLElement, HTMLElement>

The element that is being virtualized.

items

ComputedRef<VirtualItem<T>[]>

The items that are being virtualized.

offset

Readonly<ShallowRef<number>>

The offset of the virtualized items.

size

Readonly<ShallowRef<number>>

The size of the virtualized items.

state

ShallowRef<VirtualState>

The state of the virtualized items.

Methods

scrollTo

(index: number, options?: ScrollToOptions) => void

Scroll to an item by index.

scroll

() => void

The scroll event handler.

scrollend

() => void

The scrollend event handler.

resize

(index: number, height: number) => void

Resize an item by index.

reset

() => void

Reset the virtualized items.

Operation	Throughput	Latency	Margin
Access computed items 100 times (1,000 items, cached)	`5.4M ops/s`	`186ns`	± 0.2%
Scroll to start position (1,000 items)	`1.4M ops/s`	`692ns`	± 0.6%
ScrollTo middle (1,000 items)	`17.9k ops/s`	`55.8μs`	± 4.5%
Initialize with 1,000 items	`17.4k ops/s`	`57.5μs`	± 4.7%
Resize single item (1,000 items)	`16.7k ops/s`	`59.8μs`	± 9.0%