Skip to main content
Mermaid provides a JavaScript API for programmatic diagram rendering and parsing. The API is designed to support both simple use cases and advanced integrations.

​
Architecture

Mermaid’s API has two main layers:
  1. mermaid - High-level, user-facing API with automatic queueing and error handling
  2. mermaidAPI - Lower-level internal API (deprecated for direct use)
Most users should use the mermaid export. The mermaidAPI is marked as deprecated for external use and is primarily for internal implementation.

​
Main exports

The mermaid package exports the following primary interfaces:

mermaid

High-level API with run, render, parse, and initialization methods

mermaidAPI

Low-level API (deprecated for external use)

​
Installation

Install mermaid from npm: 
npm install mermaid
Import in your JavaScript/TypeScript code: 
import mermaid from 'mermaid';

​
Core concepts

​
Initialization vs. runtime

Mermaid separates configuration (initialization) from execution:
  • initialize() - Set configuration before rendering
  • run() - Find and render diagrams in the DOM
  • render() - Render a specific diagram programmatically

​
Queue-based execution

The mermaid.render() and mermaid.parse() methods use an internal execution queue to ensure diagrams are processed serially. This prevents race conditions and ensures consistent results. 
// Multiple render calls are automatically queued
const result1 = mermaid.render('id1', 'graph TD; A-->B');
const result2 = mermaid.render('id2', 'graph LR; C-->D');

// They execute in order, one at a time
await Promise.all([result1, result2]);

​
Error handling

Mermaid provides multiple ways to handle errors:
  • suppressErrors option in run() to log instead of throw
  • parseError callback for custom error handling
  • setParseErrorHandler() to set error handler globally

​
Common workflows

​
Workflow 1: Auto-rendering on page load

The simplest approach for static sites: 
import mermaid from 'mermaid';

mermaid.initialize({ startOnLoad: true });
Mermaid will automatically find and render all elements with the .mermaid class when the page loads.

​
Workflow 2: Manual rendering

For dynamic applications: 
import mermaid from 'mermaid';

// Configure once
mermaid.initialize({ theme: 'dark' });

// Render programmatically
const element = document.querySelector('#diagram');
const { svg, bindFunctions } = await mermaid.render(
  'diagramId',
  'graph TD; A-->B'
);

element.innerHTML = svg;
bindFunctions?.(element);

​
Workflow 3: Validation and parsing

For editors and validators: 
import mermaid from 'mermaid';

// Validate syntax
try {
  const result = await mermaid.parse('graph TD; A-->B');
  console.log('Valid diagram:', result.diagramType);
} catch (error) {
  console.error('Invalid syntax:', error);
}

// Or suppress errors
const result = await mermaid.parse('invalid syntax', { suppressErrors: true });
if (result === false) {
  console.log('Invalid diagram');
}

​
API comparison

FeaturemermaidmermaidAPI
StatusRecommendedDeprecated for external use
QueueingAutomaticManual
Error handlingBuilt-inManual
Use caseAll applicationsInternal implementation

​
TypeScript support

Mermaid includes full TypeScript definitions: 
import mermaid, { type MermaidConfig, type RenderResult } from 'mermaid';

const config: MermaidConfig = {
  theme: 'dark',
  logLevel: 'error'
};

mermaid.initialize(config);

const result: RenderResult = await mermaid.render('id', 'graph TD; A-->B');

​
Next steps

mermaid API

Learn about the high-level mermaid API

Configuration

Explore configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us