@lucid-softworks/virtualizer

Headless list virtualization with dynamic measurement and stable scroll anchoring.

The virtualizer owns item sizes, visible-range calculation, overscan, and scroll targets. It does not read from the DOM or write to a scroll container, so the same deterministic core can support browser, native, and framework adapters.

Usage

import { createVirtualizer } from "@lucid-softworks/virtualizer";

const virtualizer = createVirtualizer({
  count: 100_000,
  estimateSize: () => 48,
  getItemKey: (index) => rows[index]!.id,
  initialViewportSize: 600,
  overscan: 5,
});

virtualizer.setViewport(4_800, 600);

const { items, totalSize } = virtualizer.getSnapshot();

Each virtual item contains its index, stable key, start, size, and end. Render the returned items inside a spacer with totalSize on the main scrolling axis.

Dynamic measurement

Supply measured sizes after rendering:

const adjustment = virtualizer.measureMany([
  { index: 100, size: 52 },
  { index: 101, size: 71 },
]);

The returned adjustment is the scroll delta required to keep the first visible item anchored when content above it changes size. Framework adapters should apply that adjustment to the real scroll container.

Measurements are stored by item key. Updating options after prepending or reordering data preserves known sizes and keeps the first visible keyed item at the same viewport position:

const adjustment = virtualizer.setOptions({
  count: rows.length,
  estimateSize: () => 48,
  getItemKey: (index) => rows[index]!.id,
});

Pass { preserveAnchor: false } as the second argument when a data replacement should retain the raw scroll offset instead.

Scroll targets

getOffsetForIndex() calculates a clamped target using start, center, end, or auto alignment:

const offset = virtualizer.getOffsetForIndex(50_000, { align: "center" });

The core returns offsets without performing scrolling.