Large activity log
Render only visible rows from thousands of fixed or variable-height events.
Components / Data
Render long lists efficiently with fixed or dynamic row heights and native scrolling.
Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.
Deployments
1,000 records with dynamic heights
Build completed and the application is ready.
Build completed and the application is ready. Build completed and the application is ready.
Build completed and the application is ready. Build completed and the application is ready. Build completed and the application is ready.
Build completed and the application is ready.
bunx --bun @getweini/cli@latest add virtual-listImport the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.
<script setup lang="ts">
import VirtualList from './components/ui/virtual-list/VirtualList.vue'
const rows = Array.from({ length: 10000 }, (_, id) => ({ id, label: `Deployment ${id + 1}` }))
</script>
<template>
<div class="w-full max-w-md overflow-hidden rounded-ui border border-border">
<!-- biome-ignore lint/a11y/useSemanticElements: VirtualList owns spacer divs and exposes list semantics on its scrolling root. -->
<VirtualList
:items="rows"
:item-size="40"
:get-key="row => row.id"
class="h-72 w-full"
role="list"
aria-label="Deployments"
>
<template #default="{ item }">
<li class="flex h-10 items-center px-3 text-sm">{{ item.label }}</li>
</template>
</VirtualList>
</div>
</template>VirtualList handles rendering and scrolling. Add list or grid roles and labels that match your content, as shown in the example.
Render only visible rows from thousands of fixed or variable-height events.
Virtualize a filtered flat collection while keeping stable item keys.
A fixed row height and stable ID let the list calculate its window.
<script setup lang="ts">
import VirtualList from './components/ui/virtual-list/VirtualList.vue'
const rows = Array.from({ length: 10000 }, (_, id) => ({ id, label: `Deployment ${id + 1}` }))
</script>
<template>
<!-- biome-ignore lint/a11y/useSemanticElements: VirtualList owns spacer divs and exposes list semantics on its scrolling root. -->
<VirtualList
:items="rows"
:item-size="40"
:get-key="row => row.id"
class="h-72"
role="list"
aria-label="Deployments"
>
<template #default="{ item }"><li class="h-10">{{ item.label }}</li></template>
</VirtualList>
</template>Filter the source collection before passing it to the virtual window.
<script setup lang="ts">
import { computed, ref } from 'vue'
import VirtualList from './components/ui/virtual-list/VirtualList.vue'
const query = ref('')
const people = Array.from({ length: 2000 }, (_, id) => ({ id, name: `Member ${id}` }))
const visible = computed(() =>
people.filter((person) => person.name.toLowerCase().includes(query.value.toLowerCase())),
)
</script>
<template>
<label>Find member <input v-model="query"></label>
<!-- biome-ignore lint/a11y/useSemanticElements: VirtualList owns spacer divs and exposes list semantics on its scrolling root. -->
<VirtualList
:items="visible"
:item-size="48"
:get-key="person => person.id"
:overscan="6"
class="h-80"
role="list"
aria-label="Matching members"
>
<template #default="{ item }"><li class="h-12">{{ item.name }}</li></template>
</VirtualList>
</template>Enable dynamic to measure wrapped text and expanded content while retaining native scrolling. You can omit itemSize; an internal estimate is replaced as rows are measured.
<script setup lang="ts">
import { ref, useId } from 'vue'
import Button from './components/ui/button/Button.vue'
import VirtualList from './components/ui/virtual-list/VirtualList.vue'
const listId = useId()
const expanded = ref(new Set<number>())
const rows = Array.from({ length: 1000 }, (_, id) => ({
id,
label: `Deployment ${id + 1}`,
description: 'Build completed and the application is ready. '.repeat(1 + (id % 3)),
}))
function toggle(id: number) {
if (expanded.value.has(id)) expanded.value.delete(id)
else expanded.value.add(id)
}
</script>
<template>
<!-- biome-ignore lint/a11y/useSemanticElements: VirtualList exposes application-owned list semantics on its scrolling viewport. -->
<VirtualList
:items="rows"
:get-key="row => row.id"
dynamic
class="h-80"
role="list"
aria-label="Deployment details"
tabindex="0"
>
<template #default="{ item }">
<!-- biome-ignore lint/a11y/useSemanticElements: The positioned wrapper belongs to VirtualList; this content supplies listitem semantics. -->
<article role="listitem" class="space-y-2 border-b border-border px-3 py-3 text-sm">
<div class="flex items-center justify-between gap-3">
<span class="font-medium">{{ item.label }}</span>
<Button
variant="ghost"
size="sm"
:aria-expanded="expanded.has(item.id)"
:aria-controls="`${listId}-details-${item.id}`"
@click="toggle(item.id)"
>
{{ expanded.has(item.id) ? 'Hide details' : 'Show details' }}
</Button>
</div>
<p>{{ item.description }}</p>
<p
v-show="expanded.has(item.id)"
:id="`${listId}-details-${item.id}`"
class="text-muted-foreground"
>
All checks passed. The release includes the latest application changes and updated assets.
</p>
</article>
</template>
</VirtualList>
</template>Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.
| Name | Type or signature | Default | What it does |
|---|---|---|---|
itemsprop | readonly T[] | Required | Data items displayed by this component. |
getKeyprop | (item: T, index: number) => string | number | Required | Return a unique, stable key for each row. |
overscanprop | number | undefined | 3 | Extra offscreen items rendered to keep virtual scrolling smooth. |
dynamicprop | boolean | undefined | false | Measure rendered rows and observe changes to their heights. |
itemSizeprop | number | undefined | Not set | Optional estimate for unmeasured rows; defaults to 40px in dynamic mode. Required fixed row height when dynamic mode is disabled. |
defaultslot | (props: { item: T; index: number; }) => unknown | Required | Content shown inside VirtualList. |
viewportexposed | HTMLElement | null | — | Access viewport from a component template ref. |
scrollToIndexexposed | (index: number, options?: VirtualListScrollOptions) => void | — | Access scroll to index from a component template ref. |
measureexposed | () => void | — | Access measure from a component template ref. |
// packages/frameworks/vue/components/virtual-list/types.ts
// ------- TYPES -------
export type VirtualListScrollAlignment = 'start' | 'center' | 'end' | 'auto'
interface VirtualListBaseProps<T> {
items: readonly T[]
/** Return a unique, stable key for each row. */
getKey: (item: T, index: number) => string | number
overscan?: number
}
export type VirtualListProps<T> = VirtualListBaseProps<T> &
(
| {
/** Measure rendered rows and observe changes to their heights. */
dynamic: true
/** Optional estimate for unmeasured rows; defaults to 40px in dynamic mode. */
itemSize?: number
}
| {
/** Measure rendered rows and observe changes to their heights. */
dynamic?: false
/** Required fixed row height when dynamic mode is disabled. */
itemSize: number
}
)
export interface VirtualListScrollOptions {
align?: VirtualListScrollAlignment
behavior?: ScrollBehavior
}