GroupedVirtualList

Renders items grouped under collapsible section headers. Each group can be expanded or collapsed with a smooth CSS animation.

Props

groups

GroupDef<T>[]

Array of group definitions.

estimatedItemSize

number · default: 50

Estimated height of item rows.

estimatedGroupHeaderSize

number · default: 40

Estimated height of group header rows — used separately from estimatedItemSize so a taller/shorter header style doesn't throw off the scroll-position math before it's measured.

overscan

number · default: 3

Extra rows rendered outside the viewport.

keyField

string · default: 'id'

Field used as the item key.

motionBlur

boolean · default: false

Apply a CSS blur that scales with scroll velocity while scrolling fast.

stickyGroupHeaders

boolean · default: false

Keep the current group's header pinned to the top as its items scroll underneath (overlay, see below).

stickyGroupHeaders renders as a persistent overlay above the list, reusing the #group-header slot for whichever group is currently at the top of the viewport — not a real CSS position: sticky row, which can't work here because virtualized rows are position: absolute. It snaps instantly to the next group (no "push" animation).

Group Definition

GroupDef<T> — the shape of each entry in the groups prop.

interface GroupDef<T> {
  key: string // unique identifier for the group
  label: string // display label
  items: T[] // items in this group
  collapsed?: boolean // initial collapsed state
}

Slots

group-header

Scope: { group: GroupDef<T>, toggle: () => void, isCollapsed: boolean }

Custom group header.

default

Scope: { item: T, index: number, groupKey: string }

Item row content.

empty

Scope: No scope

Shown when all groups are empty.

Emits

Same as VirtualList: scroll, visible-range-change.

Exposed API (GroupedVirtualListExpose)

toggle(groupKey)

Toggle a group open/closed.

scrollTo(index, align?, options?)

Scroll to a flat row index.

getScrollElement()

Returns the element that actually scrolls — pair with VirtualScrollbar.

import type { GroupedVirtualListExpose } from 'vue-virtual-scroller-kit'

const listRef = ref<GroupedVirtualListExpose | null>(null)

listRef.value?.toggle('group-key') // toggle a group open/closed
listRef.value?.scrollTo(index) // scroll to a flat row index
listRef.value?.scrollTo(index, 'start', { behavior: 'smooth' })
listRef.value?.getScrollElement() // pair with VirtualScrollbar

Example

<script setup lang="ts">
import { ref } from 'vue'
import { GroupedVirtualList } from 'vue-virtual-scroller-kit'
import type { GroupDef, GroupedVirtualListExpose } from 'vue-virtual-scroller-kit'

interface Contact {
  id: number
  name: string
  email: string
}

const groups = ref<GroupDef<Contact>[]>([
  {
    key: 'a',
    label: 'A',
    items: [
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Aaron', email: 'aaron@example.com' },
    ],
  },
  {
    key: 'b',
    label: 'B',
    items: [{ id: 3, name: 'Bob', email: 'bob@example.com' }],
    collapsed: true,
  },
])

const listRef = ref<GroupedVirtualListExpose | null>(null)

function expandAll() {
  groups.value = groups.value.map((g) => ({ ...g, collapsed: false }))
}
function collapseAll() {
  groups.value = groups.value.map((g) => ({ ...g, collapsed: true }))
}
</script>

<template>
  <button @click="expandAll">Expand all</button>
  <button @click="collapseAll">Collapse all</button>

  <GroupedVirtualList
    ref="listRef"
    :groups="groups"
    :estimated-item-size="56"
    style="height: 500px"
  >
    <template #group-header="{ group, toggle, isCollapsed }">
      <div class="group-header" @click="toggle">
        {{ isCollapsed ? '▶' : '▼' }} {{ group.label }}
        <span>({{ group.items.length }})</span>
      </div>
    </template>

    <template #default="{ item }">
      <div class="contact-row">
        <strong>{{ item.name }}</strong>
        <span>{{ item.email }}</span>
      </div>
    </template>
  </GroupedVirtualList>
</template>