Interactive content

Documentation often needs to show mechanism — how a request flows, how state nests, where a wire docks. Nimbus splits the problem: the framework owns the tedious lifecycle, you own the render.

The headless wrapper

nimbus-docs/react ships a headless <Diagram> wrapper plus composable hooks — usePhase, useMeasure, useTabIndicator, useDiagram. The wrapper handles what’s tedious to get right: off-screen pausing, reduced-motion respect, keyboard shortcuts, error boundaries, and cross-island coordination. It renders nothing visible itself.

The smallest meaningful example — usePhase walks two steps and the rendered nodes light up in turn.

import { Diagram, usePhase } from "@cloudflare/nimbus-docs/react";
import { DiagramControls } from "@/components/react/diagram";

function PingPong() {
  const { current } = usePhase({
    steps: [{ id: "left", hold: 1500 }, { id: "right", hold: 1500 }],
    loop: true,
  });
  return (
    <div className="flex items-center justify-center gap-12 py-12">
      <Node label="Left" active={current === "left"} />
      <Node label="Right" active={current === "right"} />
    </div>
  );
}

export function Demo() {
  return (
    <Diagram label="Ping-pong">
      <DiagramControls />
      <PingPong />
    </Diagram>
  );
}

Chrome is yours

Action bars, tab groups, and play/pause controls are visual chrome you own. They install on demand into src/components/react/diagram/ via the registry:

npx @cloudflare/nimbus-docs add diagram

yarn dlx @cloudflare/nimbus-docs add diagram

pnpm dlx @cloudflare/nimbus-docs add diagram

bunx @cloudflare/nimbus-docs add diagram

Edit, restyle, or replace them freely — the hooks keep working. Sites that never author an interactive card pay nothing: react and react-dom are optional peer dependencies, loaded only when you import nimbus-docs/react.

The boundary

The framework owns behaviour; you own appearance. Embed the result in MDX with a client:visible directive so it hydrates when scrolled into view.