mermaidAPI

Lower-level API for internal Mermaid operations (deprecated for external use)

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

Feature	mermaid	mermaidAPI
Execution	Queued automatically	Direct execution
Error handling	Built-in with callbacks	Manual
Race conditions	Prevented	Possible
Status	Recommended	Deprecated
Use case	Application integration	Internal 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