mermaid

The mermaid export is the primary API for integrating Mermaid into your application. It provides a queue-based, user-friendly interface for rendering diagrams, parsing syntax, and managing configuration.

Import

import mermaid from 'mermaid';

Interface

interface Mermaid {
  // Configuration
  initialize(config: MermaidConfig): void;
  startOnLoad: boolean;

  // Core methods
  render(id: string, text: string, container?: Element): Promise<RenderResult>;
  parse(text: string, parseOptions?: ParseOptions): Promise<ParseResult>;
  run(options?: RunOptions): Promise<void>;

  // Registration
  registerExternalDiagrams(diagrams: ExternalDiagramDefinition[], options?: { lazyLoad?: boolean }): Promise<void>;
  registerLayoutLoaders(loaders: LayoutLoaderDefinition[]): void;
  registerIconPacks(iconPacks: IconPacks): void;

  // Utilities
  detectType(text: string): string;
  getRegisteredDiagramsMetadata(): Pick<ExternalDiagramDefinition, 'id'>[];
  setParseErrorHandler(handler: (err: any, hash: any) => void): void;

  // Deprecated
  init(config?: MermaidConfig, nodes?: string | HTMLElement | NodeListOf<HTMLElement>, callback?: (id: string) => unknown): Promise<void>;
  parseError?: ParseErrorFunction;
  contentLoaded(): void;
  mermaidAPI: typeof mermaidAPI; // Internal use only
}

Core methods

initialize()

Configure Mermaid before rendering diagrams.

function initialize(config: MermaidConfig): void

Call initialize() before using run() or render(). Configuration set here applies to all subsequent operations.

Example:

import mermaid from 'mermaid';

mermaid.initialize({
  theme: 'dark',
  logLevel: 'error',
  securityLevel: 'strict',
  startOnLoad: false,
  flowchart: {
    useMaxWidth: true,
    htmlLabels: true
  }
});

Parameters:

config - Configuration object. See Configuration for all options.

render()

Render a diagram to SVG code programmatically.

function render(
  id: string,
  text: string,
  container?: Element
): Promise<RenderResult>

Parameters:

id - Unique identifier for the SVG element
text - Mermaid diagram definition
container (optional) - HTML element where the SVG will be inserted

Returns: Promise<RenderResult>

interface RenderResult {
  svg: string;                                    // SVG code
  diagramType: string;                            // e.g., 'flowchart', 'sequence'
  bindFunctions?: (element: Element) => void;     // Bind event listeners
}

Example:

const element = document.querySelector('#graphDiv');
const graphDefinition = 'graph TB\na-->b';

const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
element.innerHTML = svg;
bindFunctions?.(element);

Multiple calls to render() are automatically queued and executed serially to prevent race conditions.

With container element:

const container = document.querySelector('#diagram-container');

const { svg, bindFunctions } = await mermaid.render(
  'myDiagram',
  'sequenceDiagram\nAlice->>Bob: Hello',
  container
);

// SVG is already inserted into container
bindFunctions?.(container);

parse()

Validate diagram syntax and return metadata.

function parse(
  text: string,
  parseOptions?: ParseOptions
): Promise<ParseResult | false>

Parameters:

text - Mermaid diagram definition to parse
parseOptions (optional)
- suppressErrors?: boolean - Return false instead of throwing on error

Returns: Promise<ParseResult> or Promise<false> when suppressErrors: true

interface ParseResult {
  diagramType: string;         // Detected diagram type
  config: MermaidConfig;       // Config from frontmatter/directives
}

Example:

// Throws on invalid syntax
try {
  const result = await mermaid.parse('flowchart TD\nA-->B');
  console.log(result.diagramType); // 'flowchart-v2'
} catch (error) {
  console.error('Invalid syntax');
}

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

Validation workflow:

async function validateDiagram(code) {
  const result = await mermaid.parse(code, { suppressErrors: true });

  if (result === false) {
    return { valid: false };
  }

  return {
    valid: true,
    type: result.diagramType,
    config: result.config
  };
}

run()

Find and render all diagrams in the DOM.

function run(options?: RunOptions): Promise<void>

Parameters:

options (optional)

interface RunOptions {
  querySelector?: string;                      // Default: '.mermaid'
  nodes?: ArrayLike<HTMLElement>;             // Specific nodes to render
  postRenderCallback?: (id: string) => unknown;
  suppressErrors?: boolean;                    // Default: false
}

Example - Basic usage:

import mermaid from 'mermaid';

mermaid.initialize({ theme: 'forest' });
await mermaid.run();

Example - Custom selector:

// Render all elements with class 'diagram'
await mermaid.run({ querySelector: '.diagram' });

Example - Specific nodes:

const nodes = document.querySelectorAll('.my-diagram');
await mermaid.run({ nodes });

Example - Post-render callback:

await mermaid.run({
  postRenderCallback: (id) => {
    console.log(`Rendered diagram: ${id}`);
    // Add custom event listeners, analytics, etc.
  }
});

Example - Error handling:

// Suppress errors (log but don't throw)
await mermaid.run({ suppressErrors: true });

// Or catch errors
try {
  await mermaid.run();
} catch (error) {
  console.error('Rendering failed:', error);
}

run() skips elements that have already been processed (marked with data-processed attribute). You can call it multiple times safely.

Registration methods

registerExternalDiagrams()

function registerExternalDiagrams(
  diagrams: ExternalDiagramDefinition[],
  options?: { lazyLoad?: boolean }
): Promise<void>

Parameters:

diagrams - Array of diagram definitions
options.lazyLoad - If false, load immediately. Default: true

Example:

import mermaid from 'mermaid';

const customDiagram = {
  id: 'custom',
  detector: (txt) => txt.match(/^\s*custom/) !== null,
  loader: async () => {
    return {
      diagram: {
        parser: customParser,
        db: customDb,
        renderer: customRenderer,
        styles: customStyles
      }
    };
  }
};

await mermaid.registerExternalDiagrams([customDiagram]);

registerLayoutLoaders()

function registerLayoutLoaders(loaders: LayoutLoaderDefinition[]): void

Example:

mermaid.registerLayoutLoaders([
  {
    name: 'custom-layout',
    loader: async () => await import('./custom-layout.js'),
    algorithm: 'custom'
  }
]);

registerIconPacks()

function registerIconPacks(iconPacks: Record<string, IconPack>): void

Example:

mermaid.registerIconPacks({
  'my-icons': {
    loader: async () => {
      // Return icon data
    }
  }
});

Utility methods

detectType()

Detect the diagram type from text.

function detectType(text: string): string

Example:

const type = mermaid.detectType('graph TD\nA-->B');
console.log(type); // 'flowchart-v2'

const type2 = mermaid.detectType('sequenceDiagram\nAlice->>Bob: Hi');
console.log(type2); // 'sequence'

getRegisteredDiagramsMetadata()

Get metadata for all registered diagram types.

function getRegisteredDiagramsMetadata(): Pick<ExternalDiagramDefinition, 'id'>[]

Example:

const diagrams = mermaid.getRegisteredDiagramsMetadata();
console.log(diagrams.map(d => d.id));
// ['flowchart', 'sequence', 'class', 'state', ...]

setParseErrorHandler()

Set a global error handler for parse errors.

function setParseErrorHandler(handler: (err: any, hash: any) => void): void

Example:

mermaid.setParseErrorHandler((err, hash) => {
  console.error('Parse error:', err);
  // Display error in UI
  document.getElementById('error-display').textContent = err;
});

Properties

startOnLoad

Control whether Mermaid automatically renders diagrams on page load.

startOnLoad: boolean // Default: true

Example:

import mermaid from 'mermaid';

// Disable auto-rendering
mermaid.startOnLoad = false;

It’s better to use initialize({ startOnLoad: false }) instead of setting this property directly.

Deprecated methods

init()

Deprecated. Use initialize() and run() instead.

function init(
  config?: MermaidConfig,
  nodes?: string | HTMLElement | NodeListOf<HTMLElement>,
  callback?: (id: string) => unknown
): Promise<void>

Migration:

// Old way
await mermaid.init({ theme: 'dark' }, '.diagram');

// New way
mermaid.initialize({ theme: 'dark' });
await mermaid.run({ querySelector: '.diagram' });

Complete example

import mermaid from 'mermaid';

// 1. Initialize configuration
mermaid.initialize({
  theme: 'dark',
  logLevel: 'error',
  securityLevel: 'strict',
  startOnLoad: false
});

// 2. Validate diagram syntax
const code = `
flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]
`;

const parseResult = await mermaid.parse(code, { suppressErrors: true });
if (parseResult === false) {
  console.error('Invalid diagram syntax');
  return;
}

console.log('Diagram type:', parseResult.diagramType);

// 3. Render programmatically
const element = document.querySelector('#diagram-container');
const { svg, bindFunctions } = await mermaid.render('myDiagram', code);

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

// 4. Or render all diagrams in page
await mermaid.run({
  querySelector: '.mermaid',
  postRenderCallback: (id) => {
    console.log(`Rendered: ${id}`);
  },
  suppressErrors: false
});

mermaidAPI

Lower-level API (internal use)

Configuration

Configuration options reference

Core API

Methods

Types

Import

Interface

Core methods

initialize()

render()

parse()

run()

Registration methods

registerExternalDiagrams()

registerLayoutLoaders()

registerIconPacks()

Utility methods

detectType()

getRegisteredDiagramsMetadata()

setParseErrorHandler()

Properties

startOnLoad

Deprecated methods

init()

Complete example

See also

mermaidAPI

Configuration

Core API

Methods

Types

​Import

​Interface

​Core methods

​initialize()

​render()

​parse()

​run()

​Registration methods

​registerExternalDiagrams()

​registerLayoutLoaders()

​registerIconPacks()

​Utility methods

​detectType()

​getRegisteredDiagramsMetadata()

​setParseErrorHandler()

​Properties

​startOnLoad

​Deprecated methods

​init()

​Complete example

​See also

mermaidAPI

Configuration

Import

Interface

Core methods

initialize()

render()

parse()

run()

Registration methods

registerExternalDiagrams()

registerLayoutLoaders()

registerIconPacks()

Utility methods

detectType()

getRegisteredDiagramsMetadata()

setParseErrorHandler()

Properties

startOnLoad

Deprecated methods

init()

Complete example

See also