Render Mermaid Diagrams in HTML with mermaid-element

mermaid-element is a Web Component for rendering Mermaid diagrams directly from custom HTML element markup.

It accepts Mermaid syntax as text, <template>, <code>, or <pre> content, and each element can load a specific Mermaid version or module URL.

Features

• Mermaid diagrams declared directly inside <mermaid-element>.
• Per-element Mermaid versions and custom module URLs.
• Local Mermaid instances through MermaidElement.defaultMermaid or window.mermaid.
• In-memory module caching by Mermaid URL.
• Reactive rendering after content, version, or theme changes.
• Open Shadow DOM with container and error CSS Parts.
• render and error events for application logic.
• Direct text, <template>, <code>, and <pre> diagram definitions.

How to Use mermaid-element

CDN Installation

Load the package entry as an ES module. It registers <mermaid-element> with the browser.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/mermaid-element/index.js">
</script>

Basic Usage

Place Mermaid syntax directly inside the custom element.

<mermaid-element>
flowchart LR
    Browser --> API
    API --> Database
</mermaid-element>

Install with npm

Install the package in projects that use a module bundler.

npm install mermaid-element

Import the package entry from your application code.

import 'mermaid-element';

Bundle Mermaid Locally

Install Mermaid locally when the project needs a bundled dependency, offline operation, or a locked Mermaid version.

npm install mermaid-element mermaid

Assign the imported Mermaid instance before diagrams render.

import mermaid from 'mermaid';
import { MermaidElement } from 'mermaid-element';
MermaidElement.defaultMermaid = mermaid;

A global Mermaid instance also works.

import mermaid from 'mermaid';
window.mermaid = mermaid;
import 'mermaid-element';

Load a Specific Mermaid Version

Set the mermaid attribute to a Mermaid release number.

<mermaid-element mermaid="10.9.8">
sequenceDiagram
    Client->>Server: Request
    Server-->>Client: Response
</mermaid-element>

Individual elements can use different Mermaid releases.

<mermaid-element mermaid="10.9.8">
flowchart LR
    A --> B
</mermaid-element>
<mermaid-element mermaid="11.4.1">
flowchart LR
    C --> D
</mermaid-element>

Load Mermaid from a Custom URL

The mermaid attribute also accepts an absolute URL or relative module location.

<mermaid-element
  mermaid="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs">
stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
</mermaid-element>

Use a relative location for a self-hosted Mermaid module.

<mermaid-element mermaid="/js/mermaid/mermaid.esm.min.mjs">
flowchart TD
    Start --> Finish
</mermaid-element>

Use “ for HTML Characters

Place the diagram inside <template> when labels contain raw HTML characters that the browser parser could interpret as markup.

<mermaid-element>
  <template>
flowchart LR
    A["<b>Step A</b>"] --> B["<custom-tag>"]
  </template>
</mermaid-element>

Change the Mermaid Theme

Set theme to a Mermaid built-in theme:

• default
• neutral
• dark
• forest
• base

<mermaid-element theme="dark">
flowchart LR
    Input --> Process
    Process --> Output
</mermaid-element>

Mermaid’s %%{init: ...}%% directive or YAML frontmatter can also define the theme inside the diagram syntax.

Update the property when the theme needs to change at runtime.

const diagram = document.querySelector('mermaid-element');
diagram.theme = 'forest';

Update a Diagram with JavaScript

Assign new Mermaid syntax through the diagram property.

const diagram = document.querySelector('mermaid-element');
diagram.diagram = `
flowchart LR
    Form --> Validation
    Validation --> API
    API --> Result
`;

Listen for Render and Error Events

The render event exposes the generated SVG string and Mermaid source.

const diagram = document.querySelector('mermaid-element');
diagram.addEventListener('render', (event) => {
  console.log(event.detail.svg);
  console.log(event.detail.diagram);
});

Listen for error when application code needs to react to parsing or rendering failures.

diagram.addEventListener('error', (event) => {
  console.error(event.detail.error);
  console.log(event.detail.diagram);
});

All Attributes and Properties

• diagram (string): Gets or sets the raw Mermaid definition. Setting a new value triggers rendering when the element is connected.
• mermaid (string | null): Gets or sets the Mermaid version or module URL. null returns to the default loading behavior.
• theme (string | null): Gets or sets the Mermaid theme.
• svg (SVGSVGElement | null, read-only): Returns the rendered <svg> inside the Shadow DOM.
• MermaidElement.defaultMermaid (any, static): Sets the Mermaid instance used when no explicit mermaid attribute is present.

Methods

Manually renders the current Mermaid definition.

const result = await diagram.render();

A successful call resolves to:

{
  svg: '...',
  diagram: '...'
}

Events

• render: Fires after a successful diagram render. event.detail contains { svg, diagram }.
• error: Fires after Mermaid parsing or rendering fails. event.detail contains { error, diagram }.

Loader Utilities

Import the loader utilities from the package entry when application code needs direct Mermaid source resolution or cache control.

import {
  loadMermaid,
  resolveMermaidSource,
  clearMermaidCache,
  DEFAULT_MERMAID_URL
} from 'mermaid-element';

• DEFAULT_MERMAID_URL (string): The default Mermaid 12 ESM URL.
• resolveMermaidSource(mermaidAttr): Resolves a Mermaid version or URL into the module source used by the loader.
• loadMermaid(mermaidAttr, options): Returns a Mermaid instance. options.config passes Mermaid initialization configuration, and options.defaultInstance supplies an explicit default instance.
• clearMermaidCache(): Clears cached Mermaid module imports.

Styling with Shadow Parts

The open Shadow Root exposes two documented CSS Parts:

• container: Wrapper around the rendered SVG or error state.
• error: Error message shown after a rendering failure.

mermaid-element::part(container) {
  padding: 1.25rem;
  background: #f8fafc;
  border-radius: 8px;
}
mermaid-element::part(error) {
  border-color: #dc2626;
  background-color: #fef2f2;
}

Style the Element Before Registration

Raw Mermaid syntax can appear before the browser registers the custom element.

Keep that source readable during loading with a block fallback.

mermaid-element:not(:defined) {
  display: block;
  white-space: pre-wrap;
  font-family: monospace;
}

This configuration can produce a flash when the source changes into the rendered SVG.

Hide the element until registration when raw Mermaid syntax should not appear.

mermaid-element:not(:defined) {
  display: none;
}

Alternatives & Related Resources

• Render Mermaid Diagrams to SVG or ASCII Art – beautiful-mermaid
• Draw Object-based SVG Flow Charts With obfc.js
• Drag And Drop Flowchart Builder – Drawflow