@preflow/core

Early testing phase — APIs may change before 1.0.

DOM-free predictive virtualization for lists, grids, masonry, and bottom-anchored chat.

bun add @preflow/core

import { cacheHeights, composeHeights, createFlow, fixedHeight, heightFromAspectRatio } from "@preflow/core";

const mediaHeight = heightFromAspectRatio(16 / 9);
const rowHeight = cacheHeights(
  composeHeights(24, (index, width) => measureText(rows[index].body, width), mediaHeight),
  { widthBucket: 20 },
);

const flow = createFlow({
  count: rows.length,
  getHeight: rowHeight,
  overscan: 4,
  edgeThreshold: 16,
});

flow.setContainerWidth(800);
flow.setViewport(0, 600);

for (const item of flow.getItems()) {
  console.log(item.index, item.y, item.height);
}

All four constructors return Flow, with setViewport, setContainerWidth, setCount, relayout, append/prepend helpers, scrollToIndex, and scrollToEnd. viewportRange contains items intersecting the viewport; renderRange includes overscan. visibleRange remains a deprecated compatibility alias for renderRange. scrollOffset, viewportSize, edge distances, and isAtStart/isAtEnd expose exact scroll state; edgeThreshold controls the flags and chat follow behavior.

Sizing helpers cover fixed values, arrays and typed arrays, aspect-ratio media, composed layout chrome, and cached width-dependent calculations. Cached resolvers expose invalidate(index) and clear() so content or font changes remain explicit. Invalid counts, dimensions, and non-finite or negative predicted heights fail immediately instead of entering layout state as NaN; numeric item queries and navigation indexes are bounds-safe.

Preflow never measures rendered elements. Use it when dimensions can be calculated from data and container width. See the full guide for trade-offs and framework adapters.