@preflow/react

Early testing phase — APIs may change before 1.0.

React hooks and accessible convenience components for predictive virtualization.

bun add @preflow/react

import { VirtualList } from "@preflow/react";

export function Results({ rows }) {
  return (
    <VirtualList
      aria-label="Search results"
      data={rows}
      itemKey={(row) => row.id}
      itemSize={(row, _index, width) => getRowHeight(row, width)}
      style={{ height: 480 }}
    >
      {(row) => <ResultRow row={row} />}
    </VirtualList>
  );
}

VirtualList derives count and rendering from typed data. TextList remains available as the lower-level count/index component. VirtualGrid, VirtualMasonry, and VirtualChat are compatibility names for the current low-level components while their data-first contracts are developed.

The item-layout hooks useFlow, useGrid, useMasonry, and useChat expose rendered items, total height, viewport and rendered ranges, exact edge distances and flags, isScrolling, scrollDirection, smooth scroll helpers, relayout, and onRenderRangeChange. Set edgeThreshold to control how close to an edge counts as isAtStart or isAtEnd. useProse provides the corresponding line-oriented API.

Scroll-driven render-range changes commit synchronously, so fast wheel, touchpad, scrollbar, and programmatic jumps do not paint the old off-screen range. Scroll state updates that do not change mounted items remain batched.

Convenience components retain unchanged item content between scroll updates. Keep renderItem, renderLine, custom key functions, and table render callbacks stable when their inputs have not changed so React can reuse that work.

Use initialViewport for useful SSR output, layoutKey when the size model changes, and minColumnWidth for responsive grids or masonry without writing a second ResizeObserver.

itemKey currently controls React reconciliation only. Scroll anchoring remains index-based until the key-aware mutation engine lands.

See the full guide and live examples.