Skip to content
D
Documentation

Export diagrams

how-to
3 min readUpdated

Use the mounted DiagramInstance to export the current view as PNG, SVG, or PDF, or to carry the scene graph inside an SVG or PNG for an editable round-trip.

When to use each export

  • export('png', { scale: 2 }) returns a PNG data: URL for raster images.
  • export('svg') returns SVG source. Labels remain SVG text, and vector decorations remain in the document.
  • export('pdf') returns a PDF data: URL. The PDF uses selectable text and vector paths.
  • Pass embedModel: true to PNG or SVG exports when the recipient must be able to reopen the diagram as data rather than receive a flat picture.
  • Use exportPdf() when you need synchronous PDF bytes, or exportSvgString() when you need synchronous, DOM-free SVG and its warnings.

Export after the diagram has initialized and painted. A user action such as a Download button is a suitable point; call renderNow() first when your code changes the model and must export that change immediately.

Export a mounted diagram

The following plain JavaScript example mounts real nodes and links, gives the host a height, and downloads all three visual formats. Each button changes the download, while the mounted diagram remains visible.

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

let host = document.getElementById('diagram');
if (!(host instanceof HTMLElement)) {
  host = document.createElement('div');
  host.id = 'diagram';
  document.body.append(host);
}
host.style.height = '400px';
const spec = {
  nodes: [
    { id: 'requirements', label: 'Requirements', position: { x: 40, y: 80 }, size: { width: 180, height: 70 } },
    { id: 'design', label: 'Design', position: { x: 300, y: 80 }, size: { width: 180, height: 70 } },
    { id: 'ship', label: 'Ship', position: { x: 560, y: 80 }, size: { width: 180, height: 70 } },
  ],
  edges: [{ id: 'requirements-design', source: 'requirements', target: 'design' }, { id: 'design-ship', source: 'design', target: 'ship' }],
};
const instance = render(spec, host);
instance.renderNow();

function download(href, filename) {
  const link = document.createElement('a');
  link.href = href;
  link.download = filename;
  link.click();
}

function getButton(id, label) {
  const existing = document.querySelector(`#${id}`);
  if (existing instanceof HTMLButtonElement) return existing;
  const button = document.createElement('button');
  button.id = id;
  button.textContent = label;
  document.body.append(button);
  return button;
}
const pngButton = getButton('png', 'Download PNG');
const svgButton = getButton('svg', 'Download SVG');
const pdfButton = getButton('pdf', 'Download PDF');
pngButton.addEventListener('click', async () => download(await instance.export('png', { scale: 2 }), 'diagram.png'));
svgButton.addEventListener('click', async () => {
  const svg = await instance.export('svg');
  download(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`, 'diagram.svg');
});
pdfButton.addEventListener('click', async () => download(await instance.export('pdf'), 'diagram.pdf'));

html
<button id="png">Download PNG</button>
<button id="svg">Download SVG</button>
<button id="pdf">Download PDF</button>
<div id="diagram" style="height: 400px"></div>
<script type="module" src="./diagram.js"></script>

The PNG is a raster image at twice the export scale. The SVG contains the node labels and link artwork as vector content. The PDF opens as a vector document whose labels can be selected.

The same instance in each binding shown here

The bindings expose the same instance after mount. Keep that instance in a ref, signal, or field; do not recreate it in a render. These examples export the mounted diagram as a PNG and leave it on screen.

tsx
import { useRef } from 'react';
import { GrafloriaFlow } from '@grafloria/react';
import type { DiagramInstance } from '@grafloria/react';
const nodes = [{ id: 'a', label: 'Author', position: { x: 40, y: 40 } }, { id: 'b', label: 'Review', position: { x: 260, y: 40 } }];
const edges = [{ id: 'ab', source: 'a', target: 'b' }];
export default function ExportExample() {
  const instance = useRef<DiagramInstance | null>(null);
  const exportPng = async () => { const dataUrl = await instance.current!.export('png', { scale: 2 }); const link = document.createElement('a'); link.href = dataUrl; link.download = 'diagram.png'; link.click(); };
  return <><button onClick={exportPng}>Download PNG</button><GrafloriaFlow defaultNodes={nodes} defaultEdges={edges} style={{ display: 'block', height: 400 }} onInit={(value) => { instance.current = value; }} /></>;
}

Preserve an editable artifact

Set embedModel: true on an asynchronous SVG or PNG export. The file then carries the document model alongside its visual content. Use isEditableArtifact to test an artifact and extractModel to read its embedded document. A plain image returns false and null.

js
import { render } from '@grafloria/element';
import { extractModel, isEditableArtifact } from '@grafloria/renderer';
const host = document.querySelector('#source');
if (!(host instanceof HTMLElement)) throw new Error('Missing #source');
host.style.height = '400px';
const instance = render({ nodes: [{ id: 'a', label: 'Author', position: { x: 40, y: 40 } }, { id: 'b', label: 'Review', position: { x: 260, y: 40 } }], edges: [{ id: 'ab', source: 'a', target: 'b' }] }, host);
instance.renderNow();
(async () => {
  const svg = await instance.export('svg', { embedModel: true, embedModelCreatedAt: '2020-01-01T00:00:00Z' });
  if (!isEditableArtifact(svg)) throw new Error('The model was not embedded.');
  const envelope = extractModel(svg);
  if (envelope === null) throw new Error('No model found.');
  console.log(envelope);
})();

The envelope is the scene graph recovered from the SVG. Mount the recovered document through your application’s binding to get a live diagram again. A fixed embedModelCreatedAt makes repeated exports deterministic when you compare artifact bytes.

Options that matter

OptionTypeDefaultWhat it does
scalenumber—Sets the raster scale for PNG and JPEG exports.
embedModelbooleanfalseEmbeds the model in PNG or SVG so the artifact can be reopened.
embedModelCreatedAtstring—Supplies the embedded envelope timestamp.
assetFetcherExportOptions.assetFetcher—Supplies an allowlisted fetcher for external images blocked by browser CORS during asynchronous export.

Pitfalls

  • Export the current view from the mounted instance; do not export an independent model.
  • Give the host a resolved height. See editing Mermaid diagrams.
  • Wait for initialization and a painted frame before exporting. See editing Mermaid diagrams.
  • exportSvgString() and exportPdf() are synchronous and report warnings instead of waiting for an asynchronous custom painter. Use await export('svg') or await export('pdf') when the export must wait.
  • Model embedding is opt-in. An export without embedModel: true is a flat visual artifact.

See it running

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →
Export diagrams — Grafloria · GPT-5.6 Luna