virtual-list

Render only the visible slice of a long list (fixed or variable item sizes).


Package	`@vizejs/composable/virtual-list`
Own the source	`vize lib pull composable:virtual-list`
Runtime exports	`useVirtualList`
Gzip budget	4352 B

Usage

import { useVirtualList } from "@vizejs/composable/virtual-list";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useVirtualList`	dom	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`globalThis`, `ResizeObserver`	`useElementRef`, `useResizeObserver`

API

`useVirtualList`

Render only the visible slice of a long list (fixed or variable item sizes). Offsets are prefix sums recomputed when the items change; the visible range is found by binary search, so scrolling is O(log n). Until the container is measured (always on the server) the first initialItemCount items render, so server and first client render match. The container is measured on scroll and via ResizeObserver, released with the owning reactive scope.

function useVirtualList<Item>( items: MaybeRefOrGetter<readonly Item[]>, options: UseVirtualListOptions<Item>, ): VirtualListControls<Item>

Types

`UseVirtualListOptions`

Options for useVirtualList.

Member	Type	Description
`itemSize`	`VirtualItemSize<Item>`	Item size along the scroll axis.
`overscan`?	`number`	Extra items rendered before and after the visible range.
`orientation`?	`VirtualListOrientation`	Scroll axis.
`initialItemCount`?	`number`	Items rendered before the container is measured (every server render). Keeps SSR output deterministic and non-empty for crawlers.
`host`?	`MaybeRefOrGetter<ResizeObserverHost \| null \| undefined>`	Resize-observer capability used to measure the container.

`VirtualListItem`

One rendered row/column of useVirtualList.

Member	Type	Description
`data`	`Item`	Source item.
`index`	`number`	Index in the source list.
`offset`	`number`	Start offset along the scroll axis.
`size`	`number`	Size along the scroll axis.

`VirtualContainerStyle`

Inline style for the scroll container.

Member	Type	Description
`overflowY`	`"auto" \| "hidden"`	Vertical overflow.
`overflowX`	`"auto" \| "hidden"`	Horizontal overflow.

`VirtualWrapperStyle`

Inline style for the inner wrapper that holds the rendered items.

Member	Type	Description
`width`	`string`	Wrapper width.
`height`	`string`	Wrapper height.
`marginTop`	`string`	Leading offset (`margin-top` or `margin-left`).
`marginLeft`	`string`	Leading offset for horizontal lists.
`display`	`"block" \| "flex"`	Horizontal lists lay items out in a row.

`VirtualListControls`

State and bindings returned by useVirtualList.

Member	Type	Description
`list`	`ComputedRef<readonly VirtualListItem<Item>[]>`	Items to render.
`totalSize`	`ComputedRef<number>`	Total content size along the scroll axis.
`containerProps`	`{ readonly ref: ElementRefSetter; readonly onScroll: () => void; readonly style: VirtualContainerStyle; }`	Bind on the scroll container: `v-bind="containerProps"`.
`wrapperProps`	`ComputedRef<{ readonly style: VirtualWrapperStyle }>`	Bind on the inner wrapper: `v-bind="wrapperProps"`.
`scrollTo`	`(index: number) => void`	Scroll so that the item at `index` starts at the container edge.