Diagrams

Diagram is the primary object representing a diagram.

Basic Usage

Diagram represents a global diagram context. You create a diagram by calling the Diagram function. The first parameter will be used to generate the output filename.

import { Diagram } from "diagrams-js";
import { EC2 } from "diagrams-js/aws/compute";

const diagram = Diagram("Simple Diagram");
diagram.add(EC2("web"));

const svg = await diagram.render();

This generates an SVG diagram with a single EC2 node.

Options

Direction

Control the layout direction of the diagram:

const diagram = Diagram("My Diagram", {
  direction: "LR", // Left to Right (default)
  // direction: "TB" // Top to Bottom
  // direction: "BT" // Bottom to Top
  // direction: "RL" // Right to Left
});

Curve Style

Control how edges are drawn:

const diagram = Diagram("My Diagram", {
  curvestyle: "ortho", // Orthogonal lines (default)
  // curvestyle: "curved"  // Curved lines
  // curvestyle: "spline"  // Spline curves
  // curvestyle: "polyline" // Polyline
});

See Graphviz splines documentation for more details.

Theme

Choose a color theme for clusters:

const diagram = Diagram("My Diagram", {
  theme: "pastel", // Default
  // theme: "neutral"
  // theme: "blues"
  // theme: "greens"
  // theme: "orange"
});

Filename

Specify a custom filename for saving:

const diagram = Diagram("My Diagram", {
  filename: "my_custom_name", // Will save as my_custom_name.svg
});

Custom Attributes

Pass custom Graphviz attributes:

const diagram = Diagram("My Diagram", {
  graphAttr: {
    fontsize: "15",
    bgcolor: "transparent",
  },
  nodeAttr: {
    style: "filled",
  },
  edgeAttr: {
    color: "red",
    style: "dashed",
  },
});

See Graphviz attributes reference for available options including custom attributes for graphs, nodes, and edges.

Methods

add(node)

Add a node to the diagram:

const server = diagram.add(EC2("Web Server"));

cluster(label)

Create a cluster (group) of nodes:

const cluster = diagram.cluster("Services");
const web = cluster.add(EC2("Web"));

render(options?)

Render the diagram to SVG or other formats:

// Render as SVG (default)
const svg = await diagram.render();

// Render as PNG
const png = await diagram.render({ format: "png" });

// Render as DOT
const dot = await diagram.render({ format: "dot" });

save(filepath?)

Save the diagram to a file. The behavior differs based on the environment:

Node.js: Writes the file to disk using the filesystem.

Browsers: Triggers a file download to the user's device.

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

// Or use the default filename
await diagram.save();

You can also specify render options:

// Save as PNG with specific dimensions
await diagram.save("diagram.png", {
  format: "png",
  width: 1200,
  height: 800,
});

destroy()

Clean up resources when done:

diagram.destroy();

Complete Example

import { Diagram } from "diagrams-js";
import { EC2, Lambda } from "diagrams-js/aws/compute";
import { RDS } from "diagrams-js/aws/database";
import { S3 } from "diagrams-js/aws/storage";

const diagram = Diagram("Web Architecture", {
  direction: "TB",
  theme: "pastel",
  graphAttr: {
    fontsize: "20",
  },
});

const web = diagram.add(EC2("Web Server"));
const api = diagram.add(Lambda("API"));
const db = diagram.add(RDS("Database"));
const storage = diagram.add(S3("Storage"));

web.to(api).to(db);
api.to(storage);

const svg = await diagram.render();
await diagram.save("web-architecture.svg");
diagram.destroy();

Browser Integration

In browsers, you can display the diagram directly:

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