VirtualScroller

Windowed list for long data

A list too long to render at once — thousands of log lines, a big contact list. It renders only what's in view. Under a few hundred rows, a plain list is simpler and works with find-in-page.

Basic

1第1話1,000

2第2話8,919

3第3話7,838

4第4話6,757

5第5話5,676

50,000 rows, ~12 in the DOM

<script setup lang="ts">
import { useTemplateRef } from "vue";
import { BlessButton, BlessVirtualScroller } from "blessing-ui";
const rows = Array.from({ length: 50000 }, (_, i) => ({
  id: i,
  title: `第${i + 1}話`,
  views: 1000 + ((i * 7919) % 9000),
}));
const vs = useTemplateRef<{ scrollTo: (i: number) => void }>("vs");
</script>

<template>
  <div class="col" style="max-width: 480px">
    <BlessVirtualScroller
      ref="vs"
      :items="rows"
      :item-height="36"
      height="240px"
      :row-key="(r) => r.id"
      label="Episodes"
      style="border: 1px solid var(--bless-color-border)"
    >
      <template #default="{ item, index }">
        <span style="width: 3em; color: var(--bless-color-text-muted)">{{ index + 1 }}</span>
        <span style="flex: 1">{{ item.title }}</span>
        <span>{{ item.views.toLocaleString("en-US") }}</span>
      </template>
    </BlessVirtualScroller>
    <div class="row">
      <small>50,000 rows, ~12 in the DOM</small>
      <BlessButton size="sm" variant="outline" @click="vs?.scrollTo(25000)"
        >jump to 25,001</BlessButton
      >
    </div>
  </div>
</template>

Dynamic heights

#1

lorem ipsum

#2

lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum

#3

lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum

#4

lorem ipsum lorem ipsum lorem ipsum lorem ipsum

#5

lorem ipsum lorem ipsum

rows of different heights — measured as they render, `itemHeight` is only the estimate

<script setup lang="ts">
import { BlessText, BlessVirtualScroller } from "blessing-ui";
const rows = Array.from({ length: 5000 }, (_, i) => ({
  id: i,
  text: "lorem ipsum ".repeat(1 + ((i * 7) % 9)),
}));
</script>

<template>
  <div class="col" style="max-width: 480px">
    <BlessVirtualScroller
      :items="rows"
      :item-height="40"
      dynamic
      height="240px"
      :row-key="(r) => r.id"
      label="Notes"
      style="border: 1px solid var(--bless-color-border)"
    >
      <template #default="{ item, index }">
        <div style="padding: 8px 0">
          <BlessText as="p" size="xs" muted>#{{ index + 1 }}</BlessText>
          <BlessText as="p" size="sm">{{ item.text }}</BlessText>
        </div>
      </template>
    </BlessVirtualScroller>
    <small
      >rows of different heights — measured as they render, `itemHeight` is only the estimate</small
    >
  </div>
</template>

• Each row tells screen readers the real length and its position ("12 of 10,000"), though only a window is in the page.
• itemHeight is exact; with dynamic it's an estimate and each row is measured. scrollTo(index) jumps to a row.
• Find-in-page can't see rows that aren't rendered; give long lists a search of their own.

Usage

import { BlessVirtualScroller } from "blessing-ui";

API

Props

Name	Type	Default	Description
items*	T[]	—
itemHeight*	number	—	row height in px — exact when `dynamic` is off, an estimate for unmeasured rows when it's on
dynamic	boolean	false	measure each rendered row (ResizeObserver) and lay out by real heights
height	string	"320px"
overscan	number	4	rows rendered beyond the viewport on each side
rowKey	((item: T, index: number) => string | number)	—
label	string	—

Slots

Name	Scope	Description
default	{ item: T; index: number; }