useVirtual
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.
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
API
Parameters
Input parameters accepted by this composable.
- propsrequiredIVirtualProps
- 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).
- itemsrequiredRef<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