mugen — virtualized React lists with analytic row heights

`useMugenVirtualizer(options)`

Creates and owns (across renders) the list instance for items — its measurement engine and scroll position. The item type T is inferred from items. Give the returned instance to <MugenVList>.

const  = ({  }); // instance: MugenInstance<Item>

The library never inspects T. Branch on row shape with a switch inside render; you can upgrade T to a union later without touching the engine.

`<MugenVList>`

<
  ={}
  ={() => .}
  ={() => (
    < ={12}>
      <>{.}</>
    </>
  )}
  ="16px Inter"
  ={22}
/>;

Prop	Type	Default
`instance`	`MugenInstance<T>`	—	From `useMugenVirtualizer`.
`getKey`	`(item, index) => string`	—	Stable key per item.
`render`	`(item) => ReactNode`	—	The row as a primitive tree.
`renderTop`	`() => ReactNode`	—	Scrollable content before the first row.
`renderBottom`	`() => ReactNode`	—	Scrollable content after the last row.
`font`	`Font`	—	Default font for every `Text`.
`lineHeight`	`number`	—	Default line height (px).
`maxW`	`number \| string`	∞	Content width cap (px / rem / named).
`letterSpacing` / `whiteSpace` / `wordBreak`			`Text` defaults.
`height`	`number`	fills parent	Viewport height (px).
`initialScroll`	`'top' \| 'bottom' \| { to: 'index', index, align? }`	`'top'`	Initial scroll target.
`width`	`number`	ResizeObserver	Override the measured width (SSR/tests).
`overscan`	`number`	`200`	Extra px rendered above/below the viewport.
`onTopReached`	`(index) => void`	—	Fires once when the scroll enters the top threshold.
`onBottomReached`	`(index) => void`	—	Fires once when the scroll enters the bottom threshold.
`topReachedThreshold` / `bottomReachedThreshold`	`number`	`0`	Pixel distance from the edge that counts as reached.
`className` / `style`			On the scroll container.

Row hooks

Called inside render. See State & Hooks and Effects.

const [, ] = (); // like useState; set re-measures
const  = (, ); // like useMemo; readable off-screen
(, ); // like useEffect; runs for every row

useMugenState's set and useMugenEffect re-measure the affected row in O(log n). useMugenEffect runs on a microtask after measure, for every row (on- or off-screen); return a cleanup like useEffect.

`MugenInstance`

.('row-42', { : 'smooth', : 'center' });
.(42);
.; // number of items
.(); // exact scrollable height (px)

const : ScrollToOptions = {
  : 'smooth', // 'auto' | 'smooth'
  : 'center', // 'auto' | 'start' | 'center' | 'end'
};

See Scrolling.

Primitives

Text is the pretext leaf; VStack/HStack are the layout boxes; definePrimitive(tag, { direction? }) makes a measurable box from any HTML tag. style is MeasurableStyle and className is SafeClassName — spacing/sizing through either is a type error. Escape is the exception: a declared-height box whose children are never walked (arbitrary React, e.g. a shadcn tooltip), with unrestricted style/className inside. See Primitives.

Fonts

font (typed Font) and lineHeight are Text props with <MugenVList> defaults; maxW and the other text fields are list-level. See Fonts & Layout.

Advanced / escape hatches

Export	Use
`prepareText` / `measureText` / `textHeight`	The pretext wrapper + cache.
`naturalWidth(text, font, opts)`	Tightest shrink-wrap width.
`clearTextCache()`	Drop the prepare cache.
`watchFonts` / `subscribeFonts` / `fontEpoch`	Font-load coordination.
`assertMeasurableFont(font)`	Throws on `system-ui`.

API Reference