Skip to content
D
Documentation

Export diagrams

how-to
3 min readUpdated

Export the scene graph from a painted diagram as SVG, PNG, PDF, or a deterministic server-rendered SVG. Set the output width and height explicitly for headless output; browser exports use the live instance.

When to use each entry point

Use a DiagramInstance when the diagram is mounted. Its export() method returns a promise: SVG is a raw SVG string, while PNG, JPEG, WebP, and PDF are data URLs. The ExportFormat values are 'png', 'svg', 'jpeg', 'webp', and 'pdf'.

Use exportSvgString() when you need a synchronous, DOM-free SVG result. It returns an SvgExportResult, including warnings. Use exportPdf() for synchronous PDF bytes; it returns a PdfExportResult. PDF paths remain paths and text remains selectable text.

Use renderStatic when nothing is mounted. It returns a StaticRenderResult containing svg, css, html, and snapshot, and does not require a DOM.

Export a mounted diagram

Give the host a resolved height so the live diagram paints before you export it. The following sample creates download buttons, then downloads a PNG at 2× scale or a raw SVG file:

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

document.body.innerHTML = '<button id="png">Download PNG</button><button id="svg">Download SVG</button><div id="diagram" style="height:400px"></div>';
const host = document.getElementById('diagram');
if (!host) throw new Error('Missing #diagram');

const instance = render({
  nodes: [
    { id: 'a', label: 'Extract', position: { x: 40, y: 60 }, size: { width: 150, height: 66 } },
    { id: 'b', label: 'Load', position: { x: 260, y: 60 }, size: { width: 150, height: 66 } },
  ],
  edges: [{ id: 'e1', source: 'a', target: 'b' }],
}, host);

instance.renderNow();

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

document.getElementById('png')?.addEventListener('click', async () => {
  download(await instance.export('png', { scale: 2 }), 'diagram.png');
});

document.getElementById('svg')?.addEventListener('click', async () => {
  const svg = await instance.export('svg');
  download('data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg), 'diagram.svg');
});

The mounted result is the same diagram in every tab. PNG downloads as a raster data URL at 2× scale; SVG downloads as vector markup containing the node labels and edges. Pass ExportOptions such as scale, backgroundColor, viewport, or padding as the second argument.

The mounted diagram shows two connected labeled nodes below the PNG and SVG download buttons.

Export PDF

export('pdf') returns a data:application/pdf;base64,… URL. Download it like the PNG above. The resulting PDF keeps paths as paths and text as selectable text. For bytes without a data URL, call instance.exportPdf() and read its pdf Uint8Array.

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

document.body.innerHTML = '<button id="pdf">Download PDF</button><div id="pdf-diagram" style="height:400px"></div>';
const host = document.getElementById('pdf-diagram');
if (!host) throw new Error('Missing #pdf-diagram');

const instance = render({
  nodes: [
    { id: 'a', label: 'Requirements', position: { x: 40, y: 60 }, size: { width: 170, height: 66 } },
    { id: 'b', label: 'Design', position: { x: 260, y: 60 }, size: { width: 170, height: 66 } },
    { id: 'c', label: 'Ship', position: { x: 480, y: 60 }, size: { width: 170, height: 66 } },
  ],
  edges: [{ id: 'e1', source: 'a', target: 'b' }, { id: 'e2', source: 'b', target: 'c' }],
}, host);

instance.renderNow();
document.getElementById('pdf')?.addEventListener('click', async () => {
  const link = document.createElement('a');
  link.href = await instance.export('pdf');
  link.download = 'diagram.pdf';
  link.click();
});

Render a deterministic SVG without mounting

Pass nodes, edges, and explicit dimensions to renderStatic(). width and height are CSS-pixel dimensions; standalone: true adds the SVG namespace so svg can be written as a file. The result is a styled artifact when you place css in a <style> element:

ts
import { renderStatic } from '@grafloria/element';

const result = renderStatic({
  nodes: [
    { id: 'a', label: 'Extract', position: { x: 40, y: 40 }, size: { width: 150, height: 66 } },
    { id: 'b', label: 'Load', position: { x: 260, y: 40 }, size: { width: 150, height: 66 } },
  ],
  edges: [{ id: 'e1', source: 'a', target: 'b' }],
  width: 520,
  height: 300,
  standalone: true,
});

const fileContents = result.svg.replace(/^<svg([^>]*)>/, '<svg$1><style>' + result.css + '</style>');
document.body.innerHTML = '<div id="preview"></div><div id="fingerprint"></div>';
const preview = document.getElementById('preview');
if (!preview) throw new Error('Missing #preview');
preview.innerHTML = fileContents;

let hash = 0x811c9dc5;
for (let index = 0; index < fileContents.length; index += 1) {
  hash ^= fileContents.charCodeAt(index);
  hash = Math.imul(hash, 0x01000193);
}
const fingerprint = (hash >>> 0).toString(16);
const fingerprintElement = document.getElementById('fingerprint');
if (fingerprintElement) fingerprintElement.textContent = `artifact fingerprint: ${fingerprint}`;

Repeated calls with the same spec and dimensions produce byte-identical SVG and CSS. This path uses no DOM and does not mount an interactive diagram; custom and HTML-layer nodes are not server-rendered.

The static export sample shows the rendered SVG preview and its deterministic artifact fingerprint.

Options that matter

OptionTypeDefaultWhat it does
scalenumber1Scales raster output.
qualitynumber0.92Sets JPEG/WebP quality from 0 to 1.
backgroundColorstringtransparentSets the raster background.
viewportRectanglecontent boundsSelects the world-space rectangle to export.
paddingnumber20Adds world-unit margin around content when viewport is not explicit.
widthnumber800Sets the static render width in CSS pixels.
heightnumber600Sets the static render height in CSS pixels.
fitViewbooleanfalseFrames static content instead of using viewport and zoom.

Pitfalls

  • Export after the first paint. A mounted export requires a painted canvas; call renderNow() when you need to force that synchronous paint.
  • export('svg') returns a string, not a data URL. Prefix it with data:image/svg+xml;charset=utf-8, and encode it before downloading.
  • Synchronous SVG and PDF exports cannot wait for unfinished asynchronous custom-node painters; inspect their warnings. The asynchronous export() call waits for those painters.
  • Static output is SVG only. It does not mount a live instance, and framework HTML-layer nodes are not included.

Live demos

Was this page helpful?