Canvas

Headless node-graph canvas backed by reactflow. Renders interactive agent workflows, RAG graphs, document relationships. Default Background + Controls; slot for MiniMap or custom overlays.

Installation

pnpm

pnpm dlx @hex-core/cli add canvas

Usage

tsx

import { Canvas } from "@/components/ui/canvas"

Static agent workflow

Render a fixed graph of agent steps.

tsx

import "reactflow/dist/style.css";

const nodes = [
  { id: "1", position: { x: 0, y: 0 }, data: { label: "Receive query" } },
  { id: "2", position: { x: 250, y: 100 }, data: { label: "Retrieve context" } },
];
const edges = [{ id: "e1-2", source: "1", target: "2" }];
<Canvas nodes={nodes} edges={edges} />

Editable graph with onConnect

Let the user wire nodes together.

tsx

const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
const onConnect = useCallback((p) => setEdges((e) => addEdge(p, e)), []);
<Canvas
  nodes={nodes}
  edges={edges}
  onNodesChange={onNodesChange}
  onEdgesChange={onEdgesChange}
  onConnect={onConnect}
/>

API Reference

Prop	Type	Default	Description
`nodes`required	`object`	—	Reactflow Node[] — array of node objects. See reactflow docs for shape.
`edges`required	`object`	—	Reactflow Edge[] — array of edge objects.
`onNodesChange`	`function`	—	Forwarded to ReactFlow.onNodesChange — fires on drag/select/remove.
`onEdgesChange`	`function`	—	Forwarded to ReactFlow.onEdgesChange.
`onConnect`	`function`	—	Forwarded to ReactFlow.onConnect — fires when the user draws an edge.
`hideControls`	`boolean`	false	Hide the bottom-left zoom/pan/fit controls.
`hideBackground`	`boolean`	false	Hide the dotted background.
`fitView`	`boolean`	true	Auto-fit the view to all nodes on first render.
`children`	`ReactNode`	—	Slot for MiniMap, Panel, or custom overlays inside ReactFlow.
`className`	`string`	—	Additional CSS classes on the container div.

AI Guidance

When to use

Visualize agent workflows, multi-step plans, RAG document graphs, or any DAG-shaped AI process where nodes/edges convey meaning. Pair with `useNodesState` / `useEdgesState` from reactflow for editable graphs.

When not to use

Don't use for tabular data (use `data-table`). Don't use for trees with no horizontal relationships (use `tree`). Don't use as a static SVG diagram (use `<Diagram>` with mermaid for that).

Common mistakes

Forgetting `import "reactflow/dist/style.css"` — without it, nodes render as unstyled divs and the canvas appears empty
Setting fitView={false} without specifying viewport bounds — nodes may render off-screen
Re-creating the nodes/edges arrays on every render without memoization — reactflow re-runs layout on identity change
Forgetting the canvas needs explicit height — wrap in a sized container or it collapses to 0px

Accessibility

Reactflow's accessibility is limited (the canvas is a div graph, not native semantics). For agent-workflow visualization, also expose a parallel screen-reader-friendly text/list representation of the nodes via aria-describedby.

Related components

Token budget: 380

Verified against @hex-core/components@1.12.0

Edit this page on GitHub