Render a typed, editable diagram in React, size its canvas, keep the graph in React state, and retain the mounted instance for imperative calls.
The idea
GrafloriaFlow renders node and edge data as an editable React canvas. The shared engine handles dragging, connecting, panning, and zooming.
Prerequisites and installation
Use React 17, 18, or 19 with the matching react-dom version. Install the React binding and its peer packages:
bashnpm install @grafloria/react @grafloria/engine @grafloria/renderer react react-dom @grafloria/element
Build the diagram
-
Create
App.tsxwith typed node and edge arrays.NodeSpecdescribes each box, andEdgeSpecconnects node IDs. -
Give the flow a real width and height through
style. The component's canvas uses the host's resolved size; a host with no height renders no visible canvas. -
Use
useNodesStateanduseEdgesStatefor controlled state. Pass the third value from each tuple back to the corresponding change prop. This lets a drag update React state instead of snapping the node back to the previous render. -
Capture the
DiagramInstanceinonInit. The button below callsfitView()on the mounted instance, framing the two nodes without rebuilding the component.
tsximport { useRef } from 'react';
import {
GrafloriaFlow,
useEdgesState,
useNodesState,
} from '@grafloria/react';
import type {
DiagramInstance,
EdgeSpec,
NodeSpec,
} from '@grafloria/react';
const initialNodes: NodeSpec[] = [
{
id: 'ingest',
position: { x: 60, y: 80 },
size: { width: 180, height: 80 },
data: { label: 'Ingest' },
},
{
id: 'publish',
position: { x: 380, y: 80 },
size: { width: 180, height: 80 },
data: { label: 'Publish' },
},
];
const initialEdges: EdgeSpec[] = [
{ id: 'ingest-to-publish', source: 'ingest', target: 'publish' },
];
export default function App() {
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, , onEdgesChange] = useEdgesState(initialEdges);
const instanceRef = useRef<DiagramInstance | null>(null);
function addNode() {
setNodes((current) => [
...current,
{
id: `node-${current.length}`,
position: { x: 220, y: 240 },
size: { width: 180, height: 80 },
data: { label: 'New step' },
},
]);
}
return (
<main>
<button type="button" onClick={addNode}>
Add node
</button>
<button
type="button"
onClick={() => instanceRef.current?.fitView()}
>
Fit view
</button>
<GrafloriaFlow
nodes={nodes}
edges={edges}
onNodesChange={onNodesChange}
onEdgesChange={onEdgesChange}
onInit={(instance) => {
instanceRef.current = instance;
}}
plugins
style={{ width: '100%', height: 480 }}
/>
</main>
);
}
The mounted result shows two labelled boxes joined by an edge in a 480-pixel-tall canvas. You can drag either box, pan, zoom, and draw connections. plugins adds the canvas controls, minimap, and background. Selecting Fit view calls the captured instance and frames the current content.
For a self-contained viewer or demo, use defaultNodes and defaultEdges instead. Those props seed the instance, which owns the data afterward; use controlled nodes and edges when another part of your application needs to persist or inspect the graph.
Where next
- Style a diagram explains container sizing and presentation options.
- State and data flow in React covers controlled versus uncontrolled ownership in more depth.
- Commands, events, and undo shows how to reach engine behavior through the instance.
- Try the React starter or inspect its source.
Was this page helpful?