useVirtualList

v0.0.15testeddemo

Virtualize a large list so only the items inside (and slightly around) the viewport are rendered. Supports vertical (`itemHeight`) and horizontal (`itemWidth`) layouts, fixed or per-index sizes, and an `overscan` buffer. Backed by `useElementSize` (reactive container size) and `useEventListener` (passive, auto-cleaned scroll handling). SSR-safe: renders an empty window until the container mounts.

Source Tests

Examples

const all = ref(Array.from({ length: 99999 }, (_, i) => i));
const { list, containerProps, wrapperProps, scrollTo } = useVirtualList(all, { itemHeight: 22 });
// <div v-bind="containerProps" style="height: 300px">
//   <div v-bind="wrapperProps">
//     <div v-for="{ data, index } in list" :key="index" style="height: 22px">{{ data }}</div>
//   </div>
// </div>

// Variable heights and a wider overscan buffer.
const { list } = useVirtualList(items, { itemHeight: i => (i % 2 ? 40 : 80), overscan: 10 });

Demo

Loading demo…

Signature

export function useVirtualList<T = any>(
  list: MaybeRefOrGetter<readonly T[]>,
  options: UseVirtualListOptions,
): UseVirtualListReturn<T>{ ... }

Type Parameters

T= any

Parameters

Parameter	Type	Default	Description
`list`	`MaybeRefOrGetter<readonly T[]>`	—	The full source array (may be reactive)
`options`	`UseVirtualListOptions`	—	Layout options — supply `itemHeight` (vertical) or `itemWidth` (horizontal), plus optional `overscan`

Returns

UseVirtualListReturn<T>`{ list, containerProps, wrapperProps, scrollTo }`