Skip to content
D
Documentation

Edit Mermaid diagrams

how-to
3 min readUpdated

Use this when a Mermaid file needs a live, editable canvas: load supported text into a mounted diagram, edit the text or the canvas, and write Mermaid-compatible text back with Grafloria's layout in its sidecar.

What you get

The live handle is a DiagramInstance. Its loadText() method parses Mermaid-compatible text and reconciles the result into the existing canvas; exportText() returns Mermaid-compatible text with a lossless %%grafloria:document sidecar by default. Mermaid renderers ignore the sidecar, while Grafloria reads it to restore positions, sizes, styles, ports, and groups.

The text body carries the human-editable structure and labels. If a body hash detects a hand edit, the edited body supplies the nodes, edges, labels, and shapes; the sidecar remains the base for information Mermaid cannot express. An untouched export loads from the sidecar. A recognized but unsupported type returns unsupported instead of silently drawing the wrong diagram.

Supported types are flowchart/graph, erDiagram, classDiagram, stateDiagram/stateDiagram-v2, architecture-beta, and block-beta.

Import, edit, and export

  1. Give the canvas a real height and mount it with render. The spec argument is diagram data; Mermaid text enters through the instance's text methods.
  2. Call loadText() with the Mermaid source. Keep the returned result if you need to inspect source, bodyEdited, sidecarMerged, or unsupported.
  3. Let the user edit the text, then call loadText() again. The mounted canvas updates without replacing its listeners, plugins, or renderer.
  4. Call exportText() after canvas edits or text edits. Save the returned string, including its sidecar, when Grafloria positions must survive the next import.

The following JavaScript sample renders three nodes, loads Mermaid text into that mounted instance, changes Build to Verify, and exports the resulting text.

js
import { render } from '@grafloria/element';

const host = document.getElementById('canvas');
if (!(host instanceof HTMLElement)) {
  throw new Error('Missing #canvas element');
}
host.style.height = '400px';

const instance = render({
  nodes: [
    { id: 'start', position: { x: 80, y: 80 }, size: { width: 140, height: 60 }, data: { label: 'Start' } },
    { id: 'work', position: { x: 320, y: 80 }, size: { width: 140, height: 60 }, data: { label: 'Work' } },
    { id: 'done', position: { x: 560, y: 80 }, size: { width: 140, height: 60 }, data: { label: 'Done' } },
  ],
  edges: [
    { id: 'e1', source: 'start', target: 'work' },
    { id: 'e2', source: 'work', target: 'done' },
  ],
}, host);

const source = `flowchart LR
  start[Start] --> work[Work]
  work --> done[Done]`;
const imported = instance.loadText(source);
if (imported.unsupported) {
  throw new Error(`Unsupported diagram: ${imported.unsupported}`);
}

const edited = source.replace('work[Work]', 'work[Verify]');
instance.loadText(edited);
const savedMermaid = instance.exportText();
console.log(savedMermaid);

html
<div id="canvas" style="height:400px"></div>

The canvas first shows the imported Start → Work → Done flow, then Start → Verify → Done. savedMermaid contains a Mermaid body and the sidecar that preserves Grafloria geometry.

The canvas and Mermaid text pane show the edited middle node while the surrounding nodes remain in place.

Use the framework binding

Each binding gives you the same live instance. The following examples use the repository's front-door pattern: initial nodes and edges render in the component, the ready/init callback stores the instance, and a button performs the text round-trip.

js
import { render } from '@grafloria/element';

const host = document.getElementById('canvas');
if (!(host instanceof HTMLElement)) throw new Error('Missing #canvas');
host.style.height = '400px';
const instance = render({
  nodes: [{ id: 'a', position: { x: 60, y: 80 }, size: { width: 140, height: 60 }, data: { label: 'Start' } }, { id: 'b', position: { x: 300, y: 80 }, size: { width: 140, height: 60 }, data: { label: 'Done' } }],
  edges: [{ id: 'e1', source: 'a', target: 'b' }],
}, host);

const result = instance.loadText('flowchart LR\n  a[Start] --> b[Done]');
if (result.unsupported) throw new Error(result.unsupported);
const text = instance.exportText();
console.log(text);

In every tab, Load changes the mounted diagram and Export replaces the editor text with the current diagram's Mermaid text. Give the host or component a height; a heightless canvas has no drawing area.

The mounted canvas renders the imported flow beside its Mermaid text.

Parse before loading

Use importDiagramText when you need a model or a support check before choosing what to mount. It returns an ImportTextResult. For an untouched sidecar export, source is sidecar; for a hand-edited body it is text and sidecarMerged reports that Grafloria applied the body onto the sidecar document.

ts
import { importDiagramText } from '@grafloria/engine';

const result = importDiagramText('sequenceDiagram\n  Alice->>Bob: Hello');
if (result.unsupported) {
  const message = `Unsupported Mermaid type: ${result.unsupported}`;
  document.body.append(message);
} else {
  console.log(result.diagram.getNodes().length);
}

Do not treat a recognized unsupported type as an empty diagram. Keep the current canvas and report result.unsupported to the user.

Options that affect import

optiontypedefaultwhat it does
prefer'auto' | 'sidecar' | 'text''auto'Chooses the sidecar or Mermaid body when both exist. auto uses an unchanged sidecar, while a changed body is applied as text; sidecar forces the document; text forces the parsed body without the sidecar merge.

Pass the option to either importDiagramText(text, options) or the mounted instance's loadText(text, options).

Live demos

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →