Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Data

VirtualList

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.

Interactive showcase

Deployments

1,000 records with dynamic heights

Live
Deployment 0001Review

Build completed and the application is ready.

Deployment 0002Healthy

Build completed and the application is ready. Build completed and the application is ready.

Deployment 0003Healthy

Build completed and the application is ready. Build completed and the application is ready. Build completed and the application is ready.

Deployment 0004Running

Build completed and the application is ready.

Install

Run in your project
bunx --bun @getweini/cli@latest add virtual-list

Start with this example

Import 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.

  • Deployment 1
  • Deployment 2
  • Deployment 3
  • Deployment 4
  • Deployment 5
  • Deployment 6
  • Deployment 7
  • Vue
    <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.

    When to use it

    Large activity log

    Render only visible rows from thousands of fixed or variable-height events.

    Searchable directory

    Virtualize a filtered flat collection while keeping stable item keys.

    More examples

    Deployment log

    A fixed row height and stable ID let the list calculate its window.

    Deployment log
    <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>

    Filtered directory

    Filter the source collection before passing it to the virtual window.

    Filtered directory
    <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&nbsp;<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>

    Dynamic item heights

    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.

    Dynamic item heights
    <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>

    Complete API

    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.

    VirtualList

    Complete API for VirtualList
    NameType or signatureDefaultWhat it does
    itemspropreadonly T[]RequiredData items displayed by this component.
    getKeyprop(item: T, index: number) => string | numberRequiredReturn a unique, stable key for each row.
    overscanpropnumber | undefined3Extra offscreen items rendered to keep virtual scrolling smooth.
    dynamicpropboolean | undefinedfalseMeasure rendered rows and observe changes to their heights.
    itemSizepropnumber | undefinedNot setOptional 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; }) => unknownRequiredContent shown inside VirtualList.
    viewportexposedHTMLElement | 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.
    Public type definitions
    Public types
    // 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
    }

    Implementation notes

    • Give the viewport a height and an available width. In a flex or grid showcase, use a bounded full-width wrapper so absolutely positioned rows cannot collapse the example to zero width.
    • Fixed rows require itemSize and must match that height. Dynamic rows measure their natural height without itemSize; optionally provide it to override the initial 40px estimate.
    • Use stable keys from the records rather than their changing positions after sorting or filtering.
    • Dynamic scrollToIndex refines estimated offsets with immediate scrolling. Smooth behavior remains available for fixed rows.
    • Call measure() to clear stale cached heights after offscreen content changes or to refresh external layout changes without ResizeObserver.

    Accessibility and localization

    • Choose list or grid roles to match the rendered content, and consider a nonvirtual view when users need all items available at once.

    Source contract and editing guidance