State & Hooks

A row authored by render is a real React render path, so you reach for hooks — but mugen's hooks, not React's, because their state must be readable without mounting (the walker measures every row off-screen) and a change to it must re-measure the row. They mirror useState / useMemo / useEffect.

Call them directly inside the render function (or a plain function it calls), in the same order every render — the usual rules of hooks. They throw in an event handler or outside a list; in a nested component (a JSX element the row composes), use useMugenRow instead.

useMugenState

State that can change a row's height — an expanded flag, an edited string, loaded content. Shaped exactly like useState, but the value lives in the list instance and a set re-measures only that row (O(log n)), even off-screen.

import {
  MugenVList, Text, VStack, definePrimitive,
  useMugenState, useMugenVirtualizer,
} from '@wingleeio/mugen';

interface Thread {
  id: string;
  title: string;
  body: string;
}

const Row = definePrimitive('button');

function ThreadRow(thread: Thread) {
  const [expanded, setExpanded] = useMugenState(false);
  return (
    <Row padding={12} onClick={() => setExpanded((e) => !e)}>
      <VStack gap={4}>
        <Text font="600 15px Inter">{thread.title}</Text>
        {expanded ? <Text>{thread.body}</Text> : null}
      </VStack>
    </Row>
  );
}

export function Threads({ threads }: { threads: Thread[] }) {
  const list = useMugenVirtualizer({ items: threads });
  return (
    <MugenVList instance={list} getKey={(t) => t.id} render={ThreadRow}
      font="15px Inter" lineHeight={22} />
  );
}

There are no reducers or actions — a set is the whole API, just like React.

useMugenMemo

Derive a value per row, recomputed only when its deps change. Like useMemo, but readable in the measure walk — use it to keep expensive per-row derivation out of the hot path (the walker re-runs a row's body on every re-measure).

import { Text, VStack, useMugenMemo } from '@wingleeio/mugen';

declare function splitIntoParagraphs(md: string): string[];

interface Doc {
  id: string;
  markdown: string;
}

export function DocRow(doc: Doc) {
  const blocks = useMugenMemo(() => splitIntoParagraphs(doc.markdown), [doc.markdown]);
  return (
    <VStack gap={8} padding={12}>
      {blocks.map((b, i) => (
        <Text key={i}>{b}</Text>
      ))}
    </VStack>
  );
}

useMugenEffect

Run a side effect per row when deps change — to transform content (parse markdown, highlight, load) and then set height-affecting state. It runs for every row, on- or off-screen, so the height becomes exact the moment the work resolves. See Effects for the full pattern.

useMugenRow — hooks in nested components

The positional hooks above only work at the root of render: their identity is call order, and a nested component's call order can't be matched between the measure walk and the React render. useMugenRow(id) is the form that can go anywhere in the row's tree — it names a scope, and its methods mirror the root hooks one-to-one:

import { Text, VStack, useMugenRow } from '@wingleeio/mugen';

// A nested component the row composes — not the render root.
export function ReplyBox({ threadId, body }: { threadId: string; body: string }) {
  const row = useMugenRow(`reply:${threadId}`);
  const [open, setOpen] = row.state(false);
  return (
    <VStack onClick={() => setOpen((o) => !o)}>
      <Text font="600 13px Inter">Reply</Text>
      {open ? <Text>{body}</Text> : null}
    </VStack>
  );
}

row.state / row.memo / row.effect behave exactly like their root counterparts (state lives in the list instance, a set re-measures just that row, effects run for every row on- or off-screen); row.tween is the scoped useMugenTween. Two rules:

• id must be unique within the row — two instances of the same component need different ids, so derive one from a prop.
• Call the scope's methods unconditionally, in a fixed order — they're positional within the scope, like any hooks.

There's no re-render tax hiding in this: the scope resolves through a context whose value is one frozen object per row that never changes identity, so the context itself never re-renders anything. Each consumer subscribes to its row's version instead — which also means it stays fresh even when an ancestor element is memo-stable (useMugenMemo) and React bails out of the subtree, and the measure walk stays fresh the same way (a scoped write busts the walker's height memo for that row).

Item updates are height triggers too

When you pass new items to useMugenVirtualizer, mugen re-keys and re-measures. A row whose text now wraps to a different height re-anchors the scrollbar without a flash — through the same path as a set.