Skip to main content
The mermaidAPI export is deprecated for external use. Use the mermaid export instead for all application integration.
The mermaidAPI provides lower-level functions used internally by Mermaid. While accessible, it is marked as deprecated for external use and lacks the automatic queueing and error handling of the high-level mermaid API.

​
Import

import { mermaidAPI } from 'mermaid';
// or
import mermaid from 'mermaid';
const api = mermaid.mermaidAPI;

​
Interface

interface MermaidAPI {
  render(id: string, text: string, svgContainingElement?: Element): Promise<RenderResult>;
  parse(text: string, parseOptions?: ParseOptions): Promise<ParseResult | false>;
  initialize(userOptions?: MermaidConfig): void;
  getConfig(): MermaidConfig;
  setConfig(config: MermaidConfig): MermaidConfig;
  getSiteConfig(): MermaidConfig;
  updateSiteConfig(config: MermaidConfig): MermaidConfig;
  reset(): void;
  globalReset(): void;
  defaultConfig: MermaidConfig;
  getDiagramFromText(text: string, metadata?: { title?: string }): Promise<Diagram>;
}

​
Key differences from mermaid

FeaturemermaidmermaidAPI
ExecutionQueued automaticallyDirect execution
Error handlingBuilt-in with callbacksManual
Race conditionsPreventedPossible
StatusRecommendedDeprecated
Use caseApplication integrationInternal implementation
The high-level mermaid.render() wraps mermaidAPI.render() with automatic queueing. Multiple calls to mermaid.render() execute serially, while mermaidAPI.render() executes immediately.

​
Methods

​
render()

Render a diagram directly without queueing. 
function render(
  id: string,
  text: string,
  svgContainingElement?: Element
): Promise<RenderResult>
Parameters:
  • id - The SVG element ID
  • text - Mermaid diagram definition
  • svgContainingElement (optional) - Container element
Returns: Promise<RenderResult> 
interface RenderResult {
  svg: string;
  diagramType: string;
  bindFunctions?: (element: Element) => void;
}
Example: 
import { mermaidAPI } from 'mermaid';

mermaidAPI.initialize({ theme: 'dark' });

const { svg, bindFunctions } = await mermaidAPI.render(
  'diagram1',
  'graph TD; A-->B'
);

document.getElementById('output').innerHTML = svg;
Unlike mermaid.render(), this method does not queue executions. Calling it multiple times concurrently may cause race conditions.

​
parse()

Parse and validate diagram syntax. 
function parse(
  text: string,
  parseOptions?: ParseOptions
): Promise<ParseResult | false>
Parameters:
  • text - Diagram definition
  • parseOptions
    • suppressErrors?: boolean - Return false instead of throwing
Returns: Promise<ParseResult> or Promise<false> 
interface ParseResult {
  diagramType: string;
  config: MermaidConfig;
}
Example: 
import { mermaidAPI } from 'mermaid';

const result = await mermaidAPI.parse('flowchart TD\nA-->B');
console.log(result.diagramType); // 'flowchart-v2'

​
initialize()

Set Mermaid configuration. 
function initialize(userOptions?: MermaidConfig): void
Example: 
import { mermaidAPI } from 'mermaid';

mermaidAPI.initialize({
  theme: 'forest',
  logLevel: 'debug',
  securityLevel: 'strict'
});

​
getConfig()

Get the current merged configuration. 
function getConfig(): MermaidConfig
Example: 
const config = mermaidAPI.getConfig();
console.log(config.theme); // Current theme

​
setConfig()

Update the current configuration. 
function setConfig(config: MermaidConfig): MermaidConfig
Example: 
mermaidAPI.setConfig({ theme: 'dark' });

​
getSiteConfig()

Get the site-level configuration (set via initialize()). 
function getSiteConfig(): MermaidConfig
Example: 
const siteConfig = mermaidAPI.getSiteConfig();

​
updateSiteConfig()

Update the site-level configuration. 
function updateSiteConfig(config: MermaidConfig): MermaidConfig
Example: 
mermaidAPI.updateSiteConfig({ startOnLoad: false });

​
reset()

Reset configuration to the last initialized state. 
function reset(): void
Example: 
mermaidAPI.setConfig({ theme: 'dark' });
mermaidAPI.reset(); // Reverts to initialized config

​
globalReset()

Reset configuration to default values. 
function globalReset(): void
Example: 
mermaidAPI.globalReset(); // Resets to mermaidAPI.defaultConfig

​
getDiagramFromText()

Create a Diagram object from text (internal use). 
function getDiagramFromText(
  text: string,
  metadata?: { title?: string }
): Promise<Diagram>
Example: 
const diagram = await mermaidAPI.getDiagramFromText(
  'graph TD; A-->B',
  { title: 'My Diagram' }
);

​
Properties

​
defaultConfig

The default Mermaid configuration object. 
defaultConfig: MermaidConfig
Example: 
console.log(mermaidAPI.defaultConfig.theme); // 'default'

​
Configuration hierarchy

Mermaid merges configuration from multiple sources:
  1. defaultConfig - Built-in defaults
  2. Site config - Set via initialize() or updateSiteConfig()
  3. Diagram directives - Set in diagram text
  4. Runtime config - Set via setConfig()
// 1. Default config
console.log(mermaidAPI.defaultConfig.theme); // 'default'

// 2. Initialize site config
mermaidAPI.initialize({ theme: 'forest' });

// 3. Diagram with directive
const diagram = `
%%{init: {'theme':'dark'}}%%
graph TD
  A-->B
`;

// 4. Runtime override
mermaidAPI.setConfig({ theme: 'neutral' });

// Final theme used: 'neutral' (runtime takes precedence)

​
Implementation details

​
Processing flow

The mermaidAPI.render() method follows this internal flow:
  1. Preprocess - Extract directives and configuration from diagram text
  2. Configure - Merge configs and apply directives
  3. Parse - Create Diagram object from text
  4. Style - Generate CSS styles (theme + user styles)
  5. Render - Execute diagram-specific renderer
  6. Sanitize - Clean SVG based on security level
  7. Return - Provide SVG string and bind functions

​
Security levels

The securityLevel configuration affects rendering:
  • strict (default) - DOMPurify sanitization
  • loose - No sanitization
  • sandbox - Render in sandboxed iframe
mermaidAPI.initialize({ securityLevel: 'strict' });

​
Text size limits

Diagram text is limited to prevent performance issues: 
const MAX_TEXTLENGTH = 50_000; // characters
Exceeding this shows an error diagram: 
graph TB;a[Maximum text size in diagram exceeded];style a fill:#faa
Override via configuration: 
mermaidAPI.initialize({ maxTextSize: 100_000 });

​
Migration guide

​
From mermaidAPI to mermaid

Before: 
import { mermaidAPI } from 'mermaid';

mermaidAPI.initialize({ theme: 'dark' });

const { svg } = await mermaidAPI.render('id', 'graph TD; A-->B');
document.getElementById('output').innerHTML = svg;
After: 
import mermaid from 'mermaid';

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

const { svg } = await mermaid.render('id', 'graph TD; A-->B');
document.getElementById('output').innerHTML = svg;
Benefits:
  • Automatic execution queueing
  • Better error handling
  • Future-proof (not deprecated)

​
When to use mermaidAPI

In general, you should not use mermaidAPI directly. Use the mermaid export instead.
The only valid use cases are:
  1. Contributing to Mermaid - Working on internal implementation
  2. Accessing internal utilities - When no public API exists (consider requesting one)

​
See also

mermaid

Recommended high-level API

Configuration

Configuration options reference

Build docs developers (and LLMs) love

Get started for freeTalk to us