useVirtual

Commons
stable

Virtual-scroll engine for large datasets. Maintains a dynamic window of visible items, computes per-item offsets via a debounced binary-search algorithm, tracks scroll velocity for predictive buffering, and exposes scrollToIndex with optional animated scrolling through useGoTo. SSR-safe — all DOM access is guarded.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

useVirtual is used internally by OrigamList, OrigamSelect, OrigamDataTable, and OrigamAutocomplete. For variable-height rows, call handleItemResize from a ResizeObserver on each rendered item — the composable will update its offset cache and adjust the window accordingly.

Consumed interfaces

IVirtualProps
IGoToOptions

API

Parameters

Input parameters accepted by this composable.

props
required
IVirtualProps
Reads `itemHeight` (expected row height in px, used to estimate the initial window), `height` (container height as string / number), `scrollDuration` (ms, default 300), `scrollEasing` (easing name, default easeInOutCubic).
items
required
Ref<readonly T[]>
The full dataset ref. The composable slices this array to produce `computedItems`. Changing the ref triggers an offset recalculation.

API

Return values

Properties and methods exposed by the composable return object.

containerRef
Assign to the scrollable container element. The composable reads `scrollTop` from it and listens to `handleScroll` / `handleScrollend`.
markerRef
Assign to a zero-height element at the top of the list content area. Its `offsetTop` is used to compute an offset if there is padding or a header above the virtual list.
computedItems
The slice of items currently in the render window. Each entry carries the original `raw` item and its absolute `index` in the full list.
paddingTop
Pixel padding to add above the first rendered item to preserve the scroll height.
paddingBottom
Pixel padding to add below the last rendered item to preserve the scroll height.
scrollToIndex
Programmatically scroll the container to a specific item index. Defers the scroll if the list has not yet measured (first render not complete). Pass `{ duration: 0 }` for instant scroll.
handleScroll
Bind to the `scroll` event of the container element. Computes scroll velocity and triggers visible-items recalculation.
handleScrollend
Bind to the `scrollend` event. Resets scroll velocity and recalculates the visible window.
handleItemResize
Call when a rendered item changes its measured height. Updates the size cache and triggers an offset recalculation. Wire via a ResizeObserver on each rendered row.

Usage

Examples

Ready-to-paste usage snippets.

Virtual list with 10 000 rows

vue