REACT ARCH / DOCUMENTATION

Nodes and ports

Nodes hold serializable diagram data. React renderers and boundary math remain separate registries.

Node records

nodes.ts

node("gateway", {
  type: "service",
  label: "API gateway",
  data: { runtime: "Workers" },
  shape: "rounded-rectangle",
  width: 180,
  height: 76,
  ports: [
    { id: "request", side: "left", position: 0.5 },
    { id: "sync", side: "right", position: 0.3 },
    { id: "async", side: "right", position: 0.72 }
  ]
});

A node requires only an id. Labels, dimensions, ports, custom data, type, shape, classes, accessibility labels, and manual positions are optional.

Field	Example	Use
id	gateway	Stable identity used by edges, selection, measurement, and dragging.
type	service	Selects a renderer from nodeTypes.
data	{ runtime: "Workers" }	Application data passed to the renderer.
label	API gateway	Default visible text and accessible fallback.
shape	ellipse	Selects boundary geometry and default visual class.
width / height	180 / 76	Explicit layout dimensions.
minWidth / minHeight	140 / 56	Lower bounds for explicit or measured content.
autoSize	true	Measures rendered HTML with ResizeObserver.
position	{ x: 240, y: 80 }	Coordinates read by manual layout.
ports	[{ id: "out", side: "right" }]	Named connection points.
className	critical-service	Adds a class to the SVG node group.
ariaLabel	Primary API gateway	Overrides the accessible node name.
disabled	true	Removes selection and dragging and applies disabled styling.

Dimensions and measurement

Explicit width and height give the most stable server output. When autoSize is true, the React renderer observes the actual HTML content with ResizeObserver and reruns layout after its size settles.

Use explicit dimensions for server rendering or node components whose intrinsic size changes because of remote data.

measured-node.ts

node("message", {
  type: "message",
  data: { body: remoteText },
  autoSize: true,
  minWidth: 180,
  minHeight: 56
})

Built-in shapes

rectangle clips edges to a rectangular boundary.
rounded-rectangle uses rectangle routing geometry with rounded default visuals.
ellipse uses an exact ellipse-ray intersection.

Named ports

A port has an id, cardinal side, normalized position, along-side offset, and outward offset. The normalized position runs top to bottom on vertical sides and left to right on horizontal sides.

Port field	Default	Use
id	required	Name referenced by anchors.port.
side	required	top, right, bottom, or left.
position	0.5	Normalized position along the side.
alongOffset	0	Moves the port along its side in diagram units.
offset	0	Moves the port outward from the boundary.

anchors.ts

anchors.auto("gateway")
anchors.side("gateway", "right", 0.72, 6)
anchors.port("gateway", "async")
anchors.point(720, 240)

edge("automatic", anchors.auto("gateway"), anchors.auto("worker"))
edge("exact-side", anchors.side("gateway", "bottom", 0.25, 8), anchors.auto("queue"))
edge("named-port", anchors.port("gateway", "async"), anchors.auto("queue"))
edge("annotation", anchors.point(720, 240), anchors.auto("queue"))

Spawn sequences

Set spawn on Diagram to reveal nodes without removing them from layout. Flow mode groups connected nodes by graph depth and fades each connector between its source and target stages. Time mode follows the order of the node array.

SpawnDiagram.tsx

const diagram = useRef<DiagramHandle>(null);

<Diagram
  ref={diagram}
  {...document}
  spawn={{ mode: "flow", interval: 220, animation: "scale" }}
/>;

diagram.current?.replaySpawns();

Use fade, scale, or slide-up for the entrance. Reduced-motion preferences show the complete diagram immediately.