REACT ARCH / DOCUMENTATION

API reference

Every supported runtime export and public type, with concrete examples for the values each function expects and returns.

Entry points

Import	Contains
react-arch-diagrams	All core and React exports.
react-arch-diagrams/core	Serializable records, layout, geometry, routing, and animation helpers.
react-arch-diagrams/react	React components, hooks, renderer types, interaction, and spawn types.
react-arch-diagrams/elk	The ELK layout function and LayoutEngine adapter.
react-arch-diagrams/styles.css	Default canvas, node, edge, port, selection, and animation styles.

React exports

Export	Purpose
Diagram	Renders the diagram, camera, selection, dragging, spawning, and serialization handle.
DefaultNode	Renders node.label, or node.id when no label exists.
DefaultEdge	Renders the routed path, hit target, markers, label, selection, and edge animation.
useDiagramLayout	Runs layout and routing, reports loading and errors, and discards stale asynchronous results.

react-api.tsx

const diagramRef = useRef<DiagramHandle>(null);

type StatusData = { status: string };

function StatusNode({ node, selected, dragging }: NodeRendererProps<StatusData>) {
  return <div data-selected={selected} data-dragging={dragging}>{node.data?.status}</div>;
}

function DashedEdge(props: EdgeRendererProps) {
  return <DefaultEdge {...props} edge={{ ...props.edge, className: "dashed-edge" }} />;
}

const nodeTypes: NodeTypes<StatusData> = { default: DefaultNode, status: StatusNode };
const edgeTypes: EdgeTypes = { dashed: DashedEdge };

<Diagram
  ref={diagramRef}
  nodes={document.nodes}
  edges={document.edges}
  layout={document.layout}
  nodeTypes={nodeTypes}
  edgeTypes={edgeTypes}
  shapes={shapes}
  layoutEngine={elkLayoutEngine}
  width="100%"
  height={560}
  padding={48}
  className="system-map"
  style={{ borderRadius: 0 }}
  ariaLabel="Checkout service architecture"
  fit
  spawn={{ mode: "flow", animation: "scale" }}
  interactive={{ pan: true, zoom: true, dragNodes: true, select: true }}
  selectedNodeIds={[selectedNodeId]}
  selectedEdgeIds={[selectedEdgeId]}
  onNodeClick={(node) => setSelectedNodeId(node.id)}
  onEdgeClick={(edge) => setSelectedEdgeId(edge.id)}
  onNodeMove={(id, position) => savePosition(id, position)}
  onLayout={(result) => console.log(result.bounds)}
  onError={(error) => reportError(error)}
  empty={<p>No services</p>}
/>;

diagramRef.current?.fit();
diagramRef.current?.zoomTo(1.5, { x: 400, y: 240 });
diagramRef.current?.panTo({ x: 600, y: 300 });
diagramRef.current?.replaySpawns();
const svg = diagramRef.current?.getSvgElement();
const markup = diagramRef.current?.toSvgString();

use-diagram-layout.tsx

function RoutedPreview({ document }: { document: DiagramDocument }) {
  const { result, loading, error } = useDiagramLayout(document);

  if (loading) return <p>Calculating layout</p>;
  if (error) return <p>{error.message}</p>;
  return <pre>{JSON.stringify(result, null, 2)}</pre>;
}

Diagram props

Prop	Default	Purpose
nodes	required	Serializable node records.
edges	required	Serializable edge records.
layout	manual	Manual, row, column, grid, or layered layout.
nodeTypes	{}	Custom React node renderers keyed by node.type.
edgeTypes	{}	Custom SVG edge renderers keyed by edge.type.
shapes	built-ins	Custom boundary intersection functions keyed by node.shape.
layoutEngine	lazy ELK	Engine used when layout.type is layered.
width	100%	Diagram container width.
height	500	Diagram container height.
padding	40	Diagram units added around fitted bounds.
className	none	Class added to the outer container.
style	none	Inline styles added to the outer container.
ariaLabel	Architecture diagram	Accessible name for the SVG document.
interactive	pan, zoom, select	Boolean or individual pan, zoom, dragNodes, and select switches.
fit	true	Refits while layout changes until the user moves the camera.
selectedNodeIds	[]	Controlled node selection styling.
selectedEdgeIds	[]	Controlled edge selection styling.
spawn	false	Flow-depth or timed node entrance options.
onNodeClick	none	Reports the positioned node and mouse event.
onEdgeClick	none	Reports the routed edge and mouse event.
onNodeMove	none	Reports the node id and final position after dragging.
onLayout	none	Reports each completed layout result.
onError	inline alert	Reports layout or routing errors.
empty	null	Content rendered when nodes is empty.

Diagram handle

Method	Example
fit()	diagram.current?.fit()
zoomTo(zoom, center?)	diagram.current?.zoomTo(1.5, { x: 400, y: 240 })
panTo(center)	diagram.current?.panTo({ x: 600, y: 300 })
replaySpawns()	diagram.current?.replaySpawns()
getSvgElement()	diagram.current?.getSvgElement()
toSvgString()	diagram.current?.toSvgString()

Node spawn options

Option	Default	Values
mode	flow	flow or time
delay	0	Non-negative milliseconds before the first node.
interval	180	Milliseconds between graph layers or ordered nodes.
duration	320	Entrance duration in milliseconds.
animation	scale	fade, scale, or slide-up

Document builders

Export	Purpose
defineDiagram(document)	Keeps node and edge data inference while returning the same serializable document.
node(id, options?)	Creates a node record.
edge(id, from, to, options?)	Creates an edge record.
anchors.auto(nodeId)	Clips to the node shape toward the next route point.
anchors.side(nodeId, side, position?, offset?)	Targets a normalized position on one side.
anchors.port(nodeId, portId)	Targets a port declared on the node.
anchors.point(x, y)	Uses an absolute diagram point as an endpoint.
routes.straight()	Connects the resolved endpoints directly.
routes.elbow(axis?, radius?)	Creates one bend.
routes.orthogonal(axis?, split?, radius?, avoidance?)	Creates a middle corridor and avoids unrelated nodes by default.
routes.manual(points, radius?)	Routes through supplied intermediate points.
routes.auto(radius?, avoidance?)	Uses engine points when present, then falls back to obstacle-aware routing.
layouts.manual()	Reads node.position.
layouts.row(options?)	Places nodes left to right.
layouts.column(options?)	Places nodes top to bottom.
layouts.grid(options?)	Places nodes in measured grid cells.
layouts.layered(options?)	Requests layered ELK layout.

builders.ts

const api = node("api", {
  label: "API",
  ports: [{ id: "events", side: "right", position: 0.75 }]
});

const publish = edge("publish", anchors.port("api", "events"), anchors.auto("queue"), {
  route: routes.orthogonal("horizontal", 0.4, 10)
});

anchors.side("api", "bottom", 0.25, 6);
anchors.point(640, 180);

routes.straight();
routes.elbow("vertical", 8);
routes.orthogonal("horizontal", 0.35, 12, { clearance: 16 });
routes.manual([{ x: 300, y: 80 }, { x: 300, y: 240 }], 10);
routes.auto(8, { avoidNodes: true, avoidEdges: true });

layouts.manual();
layouts.row({ gap: 48, align: "center" });
layouts.column({ gap: 32, align: "start" });
layouts.grid({ columns: 3, columnGap: 48, rowGap: 36 });
layouts.layered({ direction: "right", spacing: 48, layerSpacing: 80 });

const document = defineDiagram({ nodes: [api, node("queue")], edges: [publish] });

Layout and document functions

Export	Purpose
computeDiagram	Runs layout and routing and returns a DiagramResult.
arrangeDocument	Runs manual, row, column, or grid layout synchronously.
resolveNodeSizes	Resolves explicit, measured, minimum, and default dimensions.
DEFAULT_NODE_SIZE	The 160 by 64 fallback size.

layout-api.ts

const measured = new Map([
  ["api", { width: 210, height: 72 }]
]);

DEFAULT_NODE_SIZE;                         // { width: 160, height: 64 }
resolveNodeSizes(document.nodes, measured);
const layout = arrangeDocument(
  { ...document, layout: layouts.grid({ columns: 2 }) },
  measured
);
const complete = await computeDiagram(document, { sizes: measured });

Geometry functions

Export	Purpose
resolveEndpoint	Resolves point, node, side, and port endpoints.
endpointNodeId	Returns the referenced node id, if the endpoint has one.
endpointCenter	Returns an endpoint point or referenced node center.
rectangleIntersection	Intersects a center ray with a rectangle.
ellipseIntersection	Intersects a center ray with an ellipse.
sidePoint	Calculates an exact position on a node side.
inferSide	Chooses the cardinal side that faces a target point.
boundsOfNodes	Calculates the union of positioned node bounds.
nodeBounds	Converts one positioned node into Bounds.
centerOf	Calculates the center of Bounds.
clamp	Constrains a number to an inclusive range.
builtInShapes	Contains rectangle, rounded-rectangle, and ellipse intersection functions.

geometry-api.ts

const bounds = { x: 20, y: 40, width: 160, height: 80 };
const toward = { x: 400, y: 100 };

clamp(1.4, 0, 1);                         // 1
centerOf(bounds);                          // { x: 100, y: 80 }
rectangleIntersection(bounds, toward);     // rectangle boundary point
ellipseIntersection(bounds, toward);       // ellipse boundary point
sidePoint(bounds, "right", 0.25, 4, 6);   // exact side point
inferSide(centerOf(bounds), toward);        // "right"
builtInShapes.ellipse.intersect(bounds, toward);

const positioned = { ...node("api"), position: { x: 20, y: 40 }, width: 160, height: 80 };
const nodes = new Map([["api", positioned]]);

nodeBounds(positioned);
endpointNodeId(anchors.auto("api"));        // "api"
endpointCenter(anchors.auto("api"), nodes); // node center
resolveEndpoint({ nodes, endpoint: anchors.side("api", "right"), toward });
boundsOfNodes([positioned], 24);

Routing functions

Export	Purpose
routeEdge	Routes one edge against a positioned-node map.
routeEdges	Routes an edge list against positioned nodes.
pointsToPath	Converts points into an SVG path with optional rounded corners.
midpointOnPolyline	Finds the length-weighted midpoint used for labels.

routing-api.ts

const points = [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 100, y: 80 }];

pointsToPath(points, 10);      // rounded SVG path string
midpointOnPolyline(points);    // point halfway along total path length

const one = routeEdge(
  edge("ab", anchors.auto("a"), anchors.auto("b")),
  positionedNodesById
);
const all = routeEdges(edges, positionedNodes, {
  shapes,
  engineRoutes: { ab: points }
});

Animation functions

Export	Purpose
prefersReducedMotion	Reads the browser reduced-motion media query.
animateElement	Runs Web Animations unless reduced motion is active.

animation-api.ts

if (!prefersReducedMotion()) {
  animateElement(card, [
    { opacity: 0, transform: "translateY(8px)" },
    { opacity: 1, transform: "translateY(0)" }
  ], { duration: 240, easing: "ease-out" });
}

ELK exports

Export	Purpose
layoutWithElk	Runs layered layout and returns positioned nodes plus engine route points.
elkLayoutEngine	Adapts layoutWithElk to the LayoutEngine contract used by computeDiagram and Diagram.

elk-api.ts

import { computeDiagram } from "react-arch-diagrams/core";
import { elkLayoutEngine, layoutWithElk } from "react-arch-diagrams/elk";

const layoutOnly = await layoutWithElk(document, measuredSizes);
const routed = await computeDiagram(document, {
  layoutEngine: elkLayoutEngine,
  sizes: measuredSizes
});

Core types

PointSizeBoundsAxisDirectionSideBuiltInShapePortSpecNodeEndpointPointEndpointEndpointStraightRouteElbowRouteRouteAvoidanceOptionsOrthogonalRouteManualRouteAutoRouteRouteSpecDiagramNode<T>EdgeAnimationDiagramEdge<T>ManualLayoutFlowLayoutGridLayoutLayeredLayoutLayoutSpecDiagramDocument<NodeData, EdgeData>PositionedNode<T>RoutedEdge<T>LayoutResult<T>DiagramResult<NodeData, EdgeData>ShapeDefinitionShapeRegistryRouteOptionsResolveEndpointOptionsLayoutEngineComputeDiagramOptions

React types

DiagramProps<NodeData, EdgeData>DiagramHandleDiagramLayoutState<NodeData, EdgeData>InteractionOptionsNodeSpawnModeNodeSpawnAnimationNodeSpawnOptionsNodeRendererProps<T>NodeRenderer<T>NodeTypesEdgeRendererProps<T>EdgeRenderer<T>EdgeTypes

Complete diagrams

The diagram recipes use these APIs in service maps, request paths, event pipelines, deployment flows, state machines, data lineage, dependency graphs, and network topology.