Pele: Render Mermaid Diagrams to SVG with JavaScript

Pele is a dependency-free JavaScript library that renders Mermaid diagrams as SVG.

It handles every built-in diagram type in Mermaid and can rearrange supported layouts for narrower containers.

Pele renders synchronously, with a choice between a raw SVG string and a mounted diagram that responds to container resizing.

You can use CSS variables to control diagram colors and fonts.

Features

• SVG output for use in HTML pages and generated content.
• Touch, mouse, and keyboard zoom controls for large diagrams.
• Source updates through a mounted diagram controller.
• Diagram labels and layout spacing that adapt to narrow widths.
• Individual diagram imports and on-demand type loading.
• Reusable parsed diagrams for rendering at different widths.
• Configurable input limits, error handling, and URL filtering.

How To Use It

Installation

Load the main JavaScript from a CDN. The script exposes the pele global and includes all built-in diagram types.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pele.global.js"></script>

Or install the package with NPM:

npm install pele

Basic Usage

Create a container and call pele.mount() with Mermaid syntax. Use a block-level container whose width does not depend on the SVG.

<div id="diagram" class="diagram-container"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/pele.global.js"></script>
<script>
  const source = `flowchart LR
    A[Mermaid source] --> B[SVG diagram]
    B --> C[Web page]`;
  pele.mount(document.getElementById('diagram'), source);
</script>

Render an SVG String with ES Modules

Use render() when an application needs an SVG string for a static preview or generated content. The function is synchronous. Match fontFamily to the CSS font used for diagram labels, especially when --pele-font is set.

import { render } from 'pele';
const source = `sequenceDiagram
  participant Client
  participant Server
  Client->>Server: Request
  Server-->>Client: Response`;
const container = document.getElementById('diagram');
const styles = getComputedStyle(container);
const fontFamily = styles.getPropertyValue('--pele-font').trim() || styles.fontFamily;
const { svg } = render(source, { fontFamily });
container.innerHTML = svg;

Update a Diagram and Handle Resizing

mount() observes container width changes, reads fonts from CSS, and returns a controller for later updates. Pending web fonts and container resizes trigger automatic redraws. Call refresh() after changing the font or moving the container. Use destroy() when you no longer need observation.

import { mount } from 'pele';
const diagram = mount(document.getElementById('diagram'), `flowchart LR
  A[Draft] --> B[Review]`);
diagram.update(`flowchart LR
  A[Draft] --> B[Review] --> C[Published]`);
// After changing the container font or moving it:
diagram.refresh();
// During component teardown:
// diagram.destroy();

For one-off render() calls, pass maxWidth when the layout needs to adapt. Your application must call render() again after a container resize. By default, supported layouts can switch direction below 640 pixels. Set autoDirection: false to preserve the direction specified in the Mermaid source.

const { svg } = render(source, {
  maxWidth: document.getElementById('diagram').clientWidth,
  autoDirection: false
});

Zoom and Pan

Mounted diagrams use zoom: 'auto' by default. Zoom becomes available when a diagram is scaled down to fit its container. Set zoom: true to enable it for every mounted diagram, or zoom: false to disable it. Controls include pinch, Ctrl/Cmd plus wheel, drag, double-click, and keyboard commands when the diagram has focus. An ordinary wheel scrolls the page.

import { mount } from 'pele';
const diagram = mount(document.getElementById('diagram'), source, {
  zoom: { always: true, maxScale: 3, controls: true }
});
// Zoom is also available from the mounted controller:
diagram.zoom?.zoomTo(1.5);

To add zoom to an SVG created with render(), use enableZoom(element, options). Call the zoom controller’s refresh() if the SVG changes.

Load Only the Diagram Types You Need

The pele entry point includes all diagram types. For smaller initial bundles, use pele/core and register individual diagram modules.

import { register, render } from 'pele/core';
import flowchart from 'pele/diagrams/flowchart';
import sequence from 'pele/diagrams/sequence';
register(flowchart, sequence);
const { svg } = render('flowchart LR\n  A --> B');

For applications that receive different diagram types at runtime, pele/lazy loads each type on first use. It includes renderAsync(), mountAsync(), and load(). When updating a diagram from mountAsync() to another type, call load() for that type before update().

import { load, renderAsync } from 'pele/lazy';
await load('flowchart');
const { svg } = await renderAsync('flowchart LR\n  A --> B');

Styling and Themes

Set CSS variables on a parent element or the root SVG (.pele). Theme color changes take effect immediately. If a font changes, call refresh() to measure label widths again. Mermaid style, classDef, and linkStyle declarations can set fixed colors that do not follow CSS theme changes.

.diagram-container {
  --pele-bg: #ffffff;
  --pele-fg: #222222;
  --pele-surface: #f3f5f8;
  --pele-surface-alt: #e8edf5;
  --pele-border: #8795a5;
  --pele-line: #334155;
  --pele-accent: #2563eb;
  --pele-font: system-ui, sans-serif;
}
@media (prefers-color-scheme: dark) {
  .diagram-container {
    --pele-bg: #111827;
    --pele-fg: #f3f4f6;
    --pele-surface: #1f2937;
    --pele-surface-alt: #374151;
    --pele-border: #6b7280;
    --pele-line: #d1d5db;
    --pele-accent: #93c5fd;
  }
}

CSS Custom Properties

Series Color Variables

Zoom Control Position Variables

The zoom buttons accept --pele-zoom-top, --pele-zoom-right, --pele-zoom-bottom, and --pele-zoom-left for positioning.

Public SVG Classes

Pele exposes these SVG classes for element-level styling. Node groups also carry a data-id attribute containing the corresponding Mermaid node ID.

To style the label of the Mermaid node start:

.pele-node[data-id="start"] .pele-label {
  fill: var(--pele-accent);
}

API Reference

Functions and Entry Points

RenderOptions

MountOptions and Mounted Controller

MountOptions inherits every RenderOptions entry above and introduces four additional options. mount() and update() display invalid diagram source inside the container.

ZoomOptions and Zoom Controller

RenderResult, LinkInfo, and Error Handling

render() returns an SVG string with dimensions, type information, and link details. Internal links refer to note identifiers and need application-controlled navigation.

Each links entry has these fields:

PeleError extends the JavaScript Error class. Unlike mount(), render() and parse() throw for parsing or rendering failures. Error messages can contain the original diagram text. Insert error text with textContent, never innerHTML.

For a UI that accepts arbitrary Mermaid text, catch PeleError and display the message safely:

import { PeleError, render } from 'pele';
try {
  document.getElementById('diagram').innerHTML = render(source).svg;
} catch (error) {
  if (!(error instanceof PeleError)) throw error;
  document.getElementById('diagram').textContent = error.message;
}

Diagram Types and Mermaid Compatibility

Pele accepts all built-in diagram types from Mermaid 12.1.0+.

Diagram Type Names in the JavaScript API

detectType() and RenderResult.type use Pele’s type names. The mermaidType field retains Mermaid’s type name for the cases where they differ.

Rendering Untrusted Diagram Text

Pele escapes labels, filters styles and URLs, and limits input and SVG length. A host application must control icon markup, link navigation, Mermaid configuration, and any stricter SVG sanitization policy. The icons callback inserts the SVG markup it returns as-is. Internal link identifiers are not filtered as URLs. Images can trigger network requests when displayed. linkSchemes and imageSchemes replace the default allowed schemes, although javascript:, data:, and vbscript: are always blocked. For time limits, run rendering in a worker that the application can terminate.

To preview untrusted text without clickable links or embedded images, disable both explicitly:

const { svg } = render(source, { links: false, images: false });

Alternatives and Related Resources

• Render Mermaid Diagrams to SVG or ASCII Art – beautiful-mermaid
• Render Mermaid Diagrams in HTML with mermaid-element
• SVG Flowchart Generator With D3.js – flowcharty