Use a diagram as the workflow document: nodes represent steps, typed ports constrain connections, the engine supplies history, and node data records execution state. The result is an editor that renders a connected workflow, rejects invalid links, can run the graph, and can save and restore the document.
When to use this
Use this pattern when users create or edit a directed process rather than view a fixed diagram.
The model remains the source of truth: keep the step configuration in data, keep connection
rules on ports, and update the live instance after execution changes.
The same engine drives every binding. The JavaScript example uses render;
Define the workflow document
Create a shared module. The two nodes have explicit input and output ports. The output carries
dataType: 'event', while the input accepts only event; a connection from the output to the
input is therefore legal, and a connection in the reverse direction is not. The live objects below are
NodeModel and
PortModel; the renderer creates them from
these specs. Use NodeSpec and
EdgeSpec for the plain data arrays.
tsimport type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
export const nodes: NodeSpec[] = [
{
id: 'trigger',
type: 'workflow-step',
position: { x: 80, y: 120 },
size: { width: 170, height: 72 },
data: { label: 'Receive commit', status: 'idle' },
ports: [
{ id: 'trigger-out', side: 'right', type: 'output', dataType: 'event' },
],
},
{
id: 'deploy',
type: 'workflow-step',
position: { x: 380, y: 120 },
size: { width: 170, height: 72 },
data: { label: 'Deploy staging', status: 'idle' },
ports: [
{ id: 'deploy-in', side: 'left', type: 'input', dataType: 'event' },
{ id: 'deploy-out', side: 'right', type: 'output', dataType: 'event' },
],
},
];
export const edges: EdgeSpec[] = [
{
id: 'trigger-to-deploy',
source: 'trigger',
sourceHandle: 'trigger-out',
target: 'deploy',
targetHandle: 'deploy-in',
type: 'orthogonal',
},
];
export function setExecutionState(
instance: import('@grafloria/renderer').DiagramInstance,
nodeId: string,
status: 'idle' | 'running' | 'success' | 'failed',
): void {
const node = instance.getModel().getNode(nodeId);
if (!node) return;
node.setData('status', status);
node.setSelected(status === 'running');
instance.render();
}
For persistence, use DiagramSerializer
in a browser-safe module:
tsimport { DiagramSerializer } from '@grafloria/engine';
import type { DiagramInstance } from '@grafloria/renderer';
export function saveDocument(instance: DiagramInstance): string {
return JSON.stringify(new DiagramSerializer().serialize(instance.getModel()));
}
export function restoreDocument(instance: DiagramInstance, text: string): void {
const document = JSON.parse(text) as ReturnType<DiagramSerializer['serialize']>;
const model = new DiagramSerializer().deserialize(document);
instance.getEngine().setDiagram(model);
instance.renderNow();
}
Use the second module in the framework samples. It serializes the complete model, including ports and links. Restoring replaces the engine's diagram and repaints the mounted canvas.
Mount it in JavaScript
Give the host a resolved height. The canvas displays the two connected steps, and the buttons
change the live model, validate it, and round-trip it through JSON. The example uses the shipped
LIGHT_THEME.
tsimport { render } from '@grafloria/element';
import { LIGHT_THEME } from '@grafloria/renderer';
import { nodes, edges, setExecutionState } from './workflow';
import { saveDocument, restoreDocument } from './workflow-persistence';
const host = document.getElementById('workflow')!;
host.style.height = '420px';
const instance = render({ nodes, edges }, host, {
theme: LIGHT_THEME,
interaction: { portVisibility: 'always' },
});
const engine = instance.getEngine();
document.getElementById('run')!.addEventListener('click', () => {
setExecutionState(instance, 'trigger', 'success');
setExecutionState(instance, 'deploy', 'running');
});
document.getElementById('validate')!.addEventListener('click', () => {
console.log(engine.validateDiagram({ validateTypes: true, validateConnections: true }));
});
document.getElementById('save')!.addEventListener('click', () => {
localStorage.setItem('workflow', saveDocument(instance));
});
document.getElementById('load')!.addEventListener('click', () => {
const text = localStorage.getItem('workflow');
if (text) restoreDocument(instance, text);
});
document.getElementById('undo')!.addEventListener('click', () => {
void engine.undo();
});
html<div id="workflow" style="height: 420px"></div>
<button id="run">Run</button>
<button id="validate">Validate</button>
<button id="save">Save</button>
<button id="load">Load</button>
<button id="undo">Undo</button>
<script type="module" src="./main.ts"></script>
Clicking Run changes the trigger to a success state and selects the deploy step as the running
step; the renderer repaints the model change. A custom node can read the stored status to draw
its own success or running badge. Dragging or connecting
nodes creates engine history entries, and Undo removes the latest user edit.
Mount it in Angular, Qwik, React, and Vue
Each binding mounts a real component with the same nodes and edges. Store the instance in the binding's mount callback; do not create it in render code. The host styles give the canvas height.
tsimport { Component } from '@angular/core';
import { GrafloriaDiagramComponent } from '@grafloria/angular';
import type { RenderOptions } from '@grafloria/element';
import type { DiagramInstance } from '@grafloria/renderer';
import { nodes, edges } from './workflow';
@Component({
standalone: true,
imports: [GrafloriaDiagramComponent],
template: '<grafloria-diagram [spec]="spec" [options]="options" (ready)="ready($event)"></grafloria-diagram>',
styles: ['grafloria-diagram { display: block; height: 420px; }'],
})
export class WorkflowComponent {
readonly spec = { nodes, edges };
readonly options: RenderOptions = { interaction: { portVisibility: 'always' } };
instance?: DiagramInstance;
ready(instance: DiagramInstance): void { this.instance = instance; }
}
tsximport { useRef, type ReactElement } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/react';
import { nodes, edges } from './workflow';
export function Workflow(): ReactElement {
const instance = useRef<DiagramInstance | null>(null);
return <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
onInit={(value) => { instance.current = value; }}
style={{ display: 'block', height: '420px' }} />;
}
vue<script setup lang="ts"> import { shallowRef } from 'vue'; import { GrafloriaFlow } from '@grafloria/vue'; import type { DiagramInstance } from '@grafloria/vue'; import { nodes, edges } from './workflow'; const instance = shallowRef<DiagramInstance | null>(null); function ready(value: DiagramInstance): void { instance.value = value; } </script> <template> <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" @init="ready" style="display: block; height: 420px" /> </template>
tsximport { component$, $, noSerialize, useSignal } from '@builder.io/qwik';
import { GrafloriaFlow, type DiagramInstance } from '@grafloria/qwik';
import { nodes, edges } from './workflow';
export default component$(() => {
const instance = useSignal<DiagramInstance>();
const ready = $((value: DiagramInstance) => { instance.value = noSerialize(value); });
return <GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} onInit$={ready}
style={{ display: 'block', height: '420px' }} />;
});
All five mounted canvases show the same connected workflow. Call getEngine() through the stored
instance for validation and undo, call getModel() to inspect or update step data, and call
renderNow() when a subsequent measurement must observe the change synchronously.
Add validation and execution
Port direction, dataType, and connection limits provide structural validation while a user draws.
For a complete document check, call validateDiagram() on the DiagramEngine
and display its returned
validation result. Your executor can walk from a trigger, set each node's status with
setData(), and call render() after each step. The renderer then shows the state your node
template reads from data.
Keep execution separate from editing: a run changes status data, while a drag or connection is a command on the shared history. For a toolbar action that edits the document, use a shipped command through the engine's command manager so the action participates in the same undo stack. See Commands, events, and undo for the command boundary and Ports and validation for custom rules.
Persistence and next steps
Store the string returned by saveDocument() in your database or browser storage. On load, call
restoreDocument() on a mounted instance. Re-register any custom renderer before mounting the
document; serialized data contains the model, not JavaScript renderer functions.
See the live workflow automation builder for insertion, editing, grouping, run state, and save/load in one editor.
The n8n-style workflow builder shows item counts, branch execution, pause/step controls, and a per-node details view.
For a smaller execution-state example, open Execute flow.
Pitfalls
- A host without a resolved height renders a blank canvas. Give it a fixed height, a viewport height, or a flex/grid size; see Style a diagram.
undo()belongs to the engine, notDiagramInstance; callinstance.getEngine().undo().- Changing node data does not rerun a declarative layout. Call the engine layout method explicitly, then repaint if you use the imperative layout path; see Auto-layout a diagram.
- A custom node needs the custom-node flag and its renderer must be registered before mount; see Create custom nodes.
Was this page helpful?