Skip to main content

Rendering

Render to SVG​

const diagram = Diagram("My Diagram");
// ... add nodes

const svg = await diagram.render();
// Returns SVG string

Render to PNG​

const png = await diagram.render({ format: "png" });
// Returns Uint8Array

Render to JPG​

const jpg = await diagram.render({ format: "jpg" });
// Returns Uint8Array

Render as Data URL​

Get the diagram as a base64 data URL for direct use in HTML:

// SVG as data URL
const svgDataUrl = await diagram.render({ dataUrl: true });
// Returns: data:image/svg+xml;base64,...

// PNG as data URL
const pngDataUrl = await diagram.render({ format: "png", dataUrl: true });
// Returns: data:image/png;base64,...

// JPG as data URL
const jpgDataUrl = await diagram.render({ format: "jpg", dataUrl: true });
// Returns: data:image/jpeg;base64,...

Browser Usage with Data URLs​

Use data URLs to display diagrams in <img> tags or download them:

const dataUrl = await diagram.render({ dataUrl: true });

// Display in an image element
const img = document.createElement("img");
img.src = dataUrl;
document.body.appendChild(img);

// Or create a download link
const link = document.createElement("a");
link.href = dataUrl;
link.download = "diagram.svg";
link.click();

Save to File​

// Auto-detects format from extension
await diagram.save("diagram.svg");
await diagram.save("diagram.png");

Render Options​

const svg = await diagram.render({
  format: "svg", // 'svg' | 'png' | 'jpg' | 'dot'
  width: 800, // Output width (for PNG/JPG)
  height: 600, // Output height (for PNG/JPG)
  scale: 2, // Scale factor (default: 2 for PNG/JPG)
  dataUrl: true, // Return as base64 data URL
  embedData: false, // Disable embedded diagram metadata in SVG
});

SVG Data Embedding​

By default, all SVG output includes embedded diagram metadata, allowing you to re-import the SVG later:

const svg = await diagram.render();
// SVG contains embedded data-diagram-json attribute

// Re-import later
const restored = await Diagram.fromSVG(svg);

To generate a clean SVG without embedded data:

const cleanSvg = await diagram.render({ embedData: false });

Import from SVG​

Restore a diagram from an SVG that was previously exported or rendered:

import { Diagram } from "diagrams-js";

// From a rendered/exported SVG string
const restored = await Diagram.fromSVG(svgString);

// Or merge into an existing diagram
const diagram = Diagram("Merged");
await diagram.import(svgString, "svg");

Browser Usage​

// Get SVG string
const svg = await diagram.render();

// Insert into DOM
document.getElementById("diagram").innerHTML = svg;

SVG DOM Manipulation​

You can attach CSS classes and data attributes to nodes, edges, and clusters, then manipulate them in the browser after rendering.

Adding CSS Classes and Data Attributes​

const diagram = Diagram("Interactive");

const server = diagram.add(
  Node("Server", {
    className: "server-node",
    dataAttrs: { team: "backend", env: "prod" },
  }),
);

const db = diagram.add(
  Node("Database", {
    className: "db-node",
    dataAttrs: { team: "data" },
  }),
);

server.to(
  Edge({
    className: "critical-edge",
    dataAttrs: { latency: "50ms" },
  }),
  db,
);

const cluster = diagram.cluster("Production", {
  className: "prod-cluster",
  dataAttrs: { region: "us-east-1" },
});

Querying SVG Elements​

After rendering and inserting into the DOM, use getElement() to access SVG elements:

const svg = await diagram.render();
document.getElementById("diagram").innerHTML = svg;

// Query from current document (browser only)
const serverEl = server.getElement();
const dbEl = db.getElement();
const edgeEl = edge.getElement();
const clusterEl = cluster.getElement();

// Or query within a specific SVG string/element
const serverEl2 = server.getElement(svg);

Adding Event Handlers​

const serverEl = server.getElement();
if (serverEl) {
  serverEl.addEventListener("click", () => {
    console.log("Server clicked!");
    serverEl.classList.add("selected");
  });

  serverEl.addEventListener("mouseenter", () => {
    serverEl.style.opacity = "0.8";
  });
}

Dynamic Styling​

// Highlight all nodes in production
const nodes = document.querySelectorAll('[data-env="prod"]');
nodes.forEach((el) => el.classList.add("highlight"));

// Dim non-critical edges
const edges = document.querySelectorAll(".edge:not(.critical-edge)");
edges.forEach((el) => (el.style.opacity = "0.5"));

The after:layout Hook​

For plugin authors, the after:layout hook fires after Graphviz produces the SVG but before format conversion (PNG/JPG). This lets you modify the SVG string and have changes reflected in raster output too.

import { HookEvent } from "diagrams-js";

const modifySvgPlugin = () => ({
  name: "svg-modifier",
  version: "1.0.0",
  apiVersion: "1.0",
  runtimeSupport: { node: true, browser: true, deno: true, bun: true },
  capabilities: [
    {
      type: "hook",
      hooks: [
        {
          event: HookEvent.AFTER_LAYOUT,
          handler: async ({ svg, diagram, format }) => {
            // Modify SVG before PNG/JPG conversion
            const modified = svg.replace(/stroke="#7b8894"/g, 'stroke="red"');
            return { svg: modified, diagram, format };
          },
        },
      ],
    },
  ],
});

const diagram = Diagram("Test");
await diagram.registerPlugins([modifySvgPlugin()]);

Node.js Usage​

import { writeFile } from "fs/promises";

const svg = await diagram.render();
await writeFile("output.svg", svg);

const png = await diagram.render({ format: "png" });
await writeFile("output.png", Buffer.from(png));

Export to JSON​

const diagram = Diagram("Web Architecture");
diagram.add(EC2("Web Server"));
diagram.add(RDS("Database"));

// Export to JSON
const json = diagram.toJSON();
console.log(JSON.stringify(json, null, 2));

JSON Output Example​

{
  "name": "Web Architecture",
  "nodes": [
    {
      "id": "n1",
      "label": "Web Server",
      "provider": "aws",
      "type": "compute",
      "resource": "EC2"
    },
    {
      "id": "n2",
      "label": "Database",
      "provider": "aws",
      "type": "database",
      "resource": "RDS"
    }
  ],
  "edges": [{ "from": "n1", "to": "n2" }]
}

Import from JSON​

Restore a diagram from JSON using the static Diagram.fromJSON() method:

import { Diagram } from "diagrams-js";

const json = {
  name: "My Architecture",
  nodes: [
    {
      id: "web",
      label: "Web Server",
      provider: "aws",
      type: "compute",
      resource: "EC2",
    },
    {
      id: "db",
      label: "Database",
      provider: "aws",
      type: "database",
      resource: "RDS",
    },
  ],
  edges: [{ from: "web", to: "db", label: "SQL" }],
};

const diagram = await Diagram.fromJSON(json);
const svg = await diagram.render();

JSON Schema​

The JSON format follows a JSON Schema for validation. Reference it in your JSON files:

{
  "$schema": "https://diagrams-js.hatemhosny.dev/schema/diagram.json",
  "name": "My Architecture",
  "nodes": [...]
}