Virtual scroll ✦Documentation has not yet been reviewed by a human.

@antadesign/virtual-scroll is a separate package that builds on Anta. Install it alongside its peers, Anta ^0.3.30 and React ^19.0.0:

npm install @antadesign/virtual-scroll @antadesign/anta react

Full bundle

Use the full bundle as the default setup. One import registers <a-virtual-scroll>, loads its stylesheet, and exports the VirtualScroll component, the typed helpers, and the types:

import { VirtualScroll } from '@antadesign/virtual-scroll/bundle'

Granular entries (advanced)

Use these only to keep the element out of a server or worker build, or to load the stylesheet yourself.

With the root entry, register the element once in the browser:

import '@antadesign/virtual-scroll/elements/a-virtual-scroll'
import { VirtualScroll } from '@antadesign/virtual-scroll'

VirtualScroll renders <a-virtual-scroll>. Drive the element directly from plain JavaScript, or from a renderer that cannot use the JSX wrapper, such as one running in a worker.

Driving the element directly

The element and the application talk through attributes and events. Every event detail is plain data, so the renderer can be a worker that reconciles the DOM from another thread.

1. The application sets count.
2. The element measures itself and fires rangechange with { start, end }.
3. The application mounts rows start to end - 1 as direct children, in order, each with a data-index attribute.
4. The element measures the rows and places them.

Input never leaves the browser thread. A wheel turn starts moving the mounted rows on the same frame, and the element fires rangechange again only when it needs different rows. Until those arrive, the gap shows faint placeholder lines.

import '@antadesign/virtual-scroll/elements/a-virtual-scroll'

const lines = Array.from({ length: 10_000 }, (_, i) => `Line ${i}`)

const list = document.createElement('a-virtual-scroll')
list.tabIndex = 0
list.setAttribute('count', String(lines.length))
list.setAttribute('height', '300')
list.addEventListener('rangechange', event => {
  const { start, end } = event.detail
  list.replaceChildren(...lines.slice(start, end).map((line, i) => {
    const row = document.createElement('div')
    row.dataset.index = String(start + i)
    row.textContent = line
    return row
  }))
})
document.body.append(list)

When the range changes

The element tracks its position as a row, the anchor, plus deltaPixels: the distance from the list’s top edge to the anchor row’s top. deltaPixels is negative once the anchor’s top has scrolled above the edge.

The range is always 2 × page + 1 rows, where a page is 2 × ceil(height / item-min-height) rows. The anchor sits near the top edge, so the range is shifted down: it holds a page minus a quarter page above the anchor, and a page plus a quarter page below it. That leaves about the same room for late rows in both scroll directions. At either end of the list the range slides instead of shrinking: it starts at row 0, or ends at the last row.

A wheel turn changes only deltaPixels, and the element moves the rows it already has. Once the anchor’s top is more than half a viewport above or below the edge, the element re-seats the anchor. The last row is the exception: it sits up to a viewport below the edge when the list is bottom aligned, so it re-seats only past a full viewport.

1. It walks from the anchor toward the content on screen, one row at a time, adding up row heights until the total reaches half a viewport. Rows shorter than item-min-height count as item-min-height. The walk stops early at the first row without a measured height, so an estimate never moves content.
2. The row it reaches becomes the anchor. deltaPixels gains the heights of the rows walked over when moving down, or loses them when moving up, so nothing moves on screen.
3. The element recomputes the range around the new anchor and fires rangechange only if the range differs from the last one.

A few cases work differently:

• An anchor row taller than the viewport stays the anchor until it has scrolled fully past, then the anchor steps one row at a time.
• Scrolling past either end of the list puts row 0 at the top edge, or the last row at the bottom edge.
• Jumps set the anchor directly, with no walk.
• Near either end, the range has slid against the end of the list, so a re-seat can leave it unchanged and fire nothing.

When the range changes, the application only needs to add the new rows and remove the old ones. Rows in both ranges can stay mounted, with their measured heights. VirtualScroll keys each row by its index, so its renderer reuses them.

Take 10,000 rows in a list with height="300" and the default item-min-height of 22, with every row exactly 22px tall. A page is 2 × ceil(300 / 22) = 28 rows, so the range is 57 rows: 21 above the anchor, the anchor, and 35 below it. Scrolling down 15px per wheel tick goes like this, at selected ticks:

The anchor re-seats about once per half viewport of scrolling: here every 10 or 11 ticks. The first three re-seats, at 165px, 315px, and 465px, fire nothing, because the range is still slid against row 0. From 615px on, each event drops about 7 rows at the top and asks for about 7 new rows at the bottom. With rows of mixed height, the walk sums their measured heights, so each step still covers about half a viewport, in fewer rows when they are tall.

When an event fires, the rows already mounted cover the screen while the new rows render. With every row at the minimum height, the worst case, about 330px of mounted rows remain below the screen when scrolling down, and about 300px above it when scrolling up: about a viewport either way. Taller rows leave more. A renderer that falls further behind than that, as on a fast fling, shows placeholder lines until it catches up.

The range also changes when:

• The anchor jumps far away: dragging the thumb, clicking the track, Home or End, reveal, and initialPosition. The whole range changes in one event, and placeholder lines show until the new rows arrive. A click on the track or a thumb drag is different: the thumb moves at once, and the rows show the newest position whose rows have arrived, so rows that render in a worker trail the thumb. Placeholders show only after 1 second without new rows.
• count changes near the end of the list, since the range ends at the last row. With follow, the anchor is the last row, so every appended row fires an event.
• The height changes, since a page depends on it.

How many rows get mounted

A list with up to max-non-virtual rows (500 by default) mounts every row, and its range changes only with count. A longer list always mounts:

4 × ceil(height / item-min-height) + 1

That’s two pages plus the anchor, at every scroll position, including both ends of the list. With the default item-min-height of 22:

The count depends only on height and item-min-height, not on how tall the rows are. Taller rows cover more pixels with the same count. At most about ceil(height / item-min-height) + 1 rows are on screen, so the list mounts about four times what it shows. The content on screen can be half a viewport away from the anchor, and the rest of the window is room for late rows: about a viewport beyond the screen, in the direction of scrolling, when the range changes. Set item-min-height close to the real smallest row: at 11, a 300px list mounts up to 113 rows.

Worker helpers

@antadesign/virtual-scroll/source exports typed helpers that import no renderer and touch no DOM:

import {
  mapVirtualScrollRange, type VirtualScrollRange, type VirtualScrollRangeSource,
} from '@antadesign/virtual-scroll/source'

type LogLine = { text: string }

function rows(lines: VirtualScrollRangeSource<LogLine>, range: VirtualScrollRange) {
  return mapVirtualScrollRange(lines, range, (line, index) =>
    h('div', { key: index, 'data-index': index }, line.text))
}

VirtualScrollItem<S> names the row type of a source, and the element’s attributes are typed: initial-position and reveal-x only accept four numbers, and event handlers receive typed details.

Each prop links to the section that demonstrates it. className, style, aria-* and data-* attributes, and standard DOM handlers such as onKeyDown pass through to the element.

Attributes

Each attribute matches the VirtualScroll prop of the same name in camel case, except max-non-virtual (maxNonVirtualItems) and the reveal-* attributes (reveal).

Events

Events do not bubble.

Slots

Size the list with height and maxHeight, or with CSS on the host. Rows are your own light-DOM elements; style them with plain CSS. scrollbarWidth sets the scrollbar size. Custom states such as :state(scrolling), the scrollbar and mark color properties, and the parts are documented on AVirtualScrollElement, so your editor shows them on hover.

a-virtual-scroll.log {
  --virtual-scroll-mark-bg: var(--text-1-warning);
}
a-virtual-scroll.log:not(:state(scrolling)) > :hover {
  background: color-mix(in oklch, var(--text-1-brand) 5%, transparent);
}

Rows and the header inherit --virtual-scroll-x, the horizontal offset. A pinned cell can use one rule that also works when the same rows render in a native scroller, where position: sticky does the pinning and the variable is unset:

.pinned {
  position: sticky;
  left: 0;
  translate: var(--virtual-scroll-x, 0px) 0;
}