Configuration

Learn how to configure Mermaid globally and per-diagram, including configuration methods, options, and best practices.

Mermaid provides extensive configuration options to control diagram rendering, appearance, and behavior. Configuration can be applied globally, per-site, or per-diagram.

Configuration hierarchy

Mermaid uses a layered configuration system:

1. Default configuration - Built-in defaults from the library
2. Site configuration - Set via initialize() or setSiteConfig()
3. Directive configuration - Per-diagram using %%{init: {}}%% syntax
4. Frontmatter configuration - Per-diagram using YAML frontmatter

Later configurations override earlier ones, with frontmatter having the highest priority.

Setting configuration

Initialize (recommended)

The standard way to configure Mermaid at application startup:

import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  theme: 'dark',
  logLevel: 'error',
  securityLevel: 'strict',
  flowchart: {
    curve: 'basis',
    padding: 20
  }
});

This should be called once before rendering any diagrams.

Frontmatter

Configure individual diagrams using YAML frontmatter:

Frontmatter has the highest priority and only affects the specific diagram.

Directives

Use directives for quick configuration changes:

Directives can be placed before or after the diagram declaration.

Runtime API

Update configuration after initialization:

import { updateSiteConfig } from 'mermaid';

// Update the site config
updateSiteConfig({
  theme: 'dark'
});

// Get current config
import { getConfig } from 'mermaid';
const config = getConfig();

Global configuration options

Core options

{
  // Automatically render diagrams on page load
  startOnLoad: true,
  
  // Maximum text length allowed in diagrams
  maxTextSize: 50000,
  
  // Use deterministic IDs for reproducible output
  deterministicIds: false,
  deterministicIDSeed: undefined,
  
  // Font family for all text
  fontFamily: '"trebuchet ms", verdana, arial, sans-serif',
  
  // Font size
  fontSize: 16,
  
  // Logging level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
  logLevel: 'fatal',
  
  // Security level: 'strict' | 'loose' | 'sandbox'
  securityLevel: 'strict',
  
  // Theme: 'default' | 'dark' | 'forest' | 'neutral' | 'base'
  theme: 'default',
  
  // Whether to use HTML labels globally
  htmlLabels: true,
}

Security configuration

The securityLevel option has important security implications when rendering user-generated content.

mermaid.initialize({
  // strict: Prevents dangerous features, encodes tags
  // loose: Allows more features (security risk with user content)
  // sandbox: Renders in sandboxed iframe (safest)
  securityLevel: 'strict',
  
  // Additional security options
  secure: [
    // Keys that cannot be overridden by directives/frontmatter
    'secure',
    'securityLevel',
    'startOnLoad',
    'maxTextSize'
  ]
});

Visual options

mermaid.initialize({
  theme: 'default',
  
  // Custom theme variables (requires theme: 'base')
  themeVariables: {
    primaryColor: '#BB2528',
    primaryTextColor: '#fff',
    primaryBorderColor: '#7C0000',
    lineColor: '#F8B229',
    secondaryColor: '#006100',
    tertiaryColor: '#fff'
  },
  
  // Custom CSS (advanced)
  themeCSS: '.node rect { fill: #f9f; }',
  
  // Custom font family
  fontFamily: 'Arial, sans-serif',
  
  // Font size in pixels
  fontSize: 16
});

Layout and rendering

mermaid.initialize({
  // Layout engine: 'dagre' | 'elk'
  layout: 'dagre',
  
  // Visual look: 'classic' | 'handDrawn'
  look: 'classic',
  
  // ELK layout options (when layout: 'elk')
  elk: {
    mergeEdges: false,
    nodePlacementStrategy: 'BRANDES_KOEPF', // 'SIMPLE' | 'NETWORK_SIMPLEX' | 'LINEAR_SEGMENTS' | 'BRANDES_KOEPF'
  }
});

Diagram-specific configuration

Each diagram type has its own configuration section:

Flowchart

mermaid.initialize({
  flowchart: {
    // Curve style: 'basis' | 'linear' | 'cardinal'
    curve: 'basis',
    
    // Padding around the diagram
    padding: 15,
    
    // Use HTML labels in nodes
    htmlLabels: true,
    
    // Default arrow marker
    defaultRenderer: 'dagre-wrapper',
    
    // Rank direction
    rankSpacing: 50,
    nodeSpacing: 50,
    
    // Wrapping width for node labels
    wrappingWidth: 200
  }
});

Sequence diagram

mermaid.initialize({
  sequence: {
    // Actor margins
    actorMargin: 50,
    
    // Box margins
    boxMargin: 10,
    boxTextMargin: 5,
    
    // Message alignment: 'left' | 'center' | 'right'
    messageAlign: 'center',
    
    // Mirror actors at bottom
    mirrorActors: true,
    
    // Note margins
    noteMargin: 10,
    
    // Show sequence numbers
    showSequenceNumbers: false,
    
    // Wrap labels
    wrap: false,
    wrapPadding: 10,
    
    // Width
    width: 150,
    height: 65,
    
    // Use max text width
    useMaxWidth: true
  }
});

Gantt

mermaid.initialize({
  gantt: {
    // Number format for tick intervals
    numberSectionStyles: 4,
    
    // Axis format
    axisFormat: '%Y-%m-%d',
    
    // Tick interval (e.g., '1day', '1week')
    tickInterval: undefined,
    
    // Use width
    useWidth: undefined,
    
    // Section font sizes
    fontSize: 11,
    sectionFontSize: 11,
    
    // Bar height
    barHeight: 20,
    barGap: 4,
    
    // Top padding
    topPadding: 50,
    
    // Left/right padding  
    leftPadding: 75,
    rightPadding: 75,
    
    // Grid line start padding
    gridLineStartPadding: 35,
    
    // Use max width
    useMaxWidth: true
  }
});

Class diagram

mermaid.initialize({
  class: {
    // Hide empty member boxes
    hideEmptyMembersBox: false,
    
    // Arrow marker: 'true' | 'false' | 'triangle' | 'cross'
    arrowMarkerAbsolute: false,
    
    // Default renderer
    defaultRenderer: 'dagre-wrapper',
    
    // Node spacing
    nodeSpacing: 50,
    rankSpacing: 50,
    
    // Diagram padding
    padding: 20,
    
    // Text height
    textHeight: 10
  }
});

State diagram

mermaid.initialize({
  state: {
    // Divider margin
    dividerMargin: 10,
    
    // State radius
    radius: 5,
    
    // Text height
    textHeight: 10,
    
    // Fork width/height
    forkWidth: 70,
    forkHeight: 7,
    
    // Mini padding
    miniPadding: 2,
    
    // Font sizes
    fontSize: 24,
    labelHeight: 16,
    edgeLengthFactor: '20',
    
    // Composition
    compositTitleSize: 35,
    
    // Node spacing
    nodeSpacing: 50,
    rankSpacing: 50,
    
    // Default renderer
    defaultRenderer: 'dagre-wrapper',
    
    // Layout
    layout: 'dagre'
  }
});

ER diagram

mermaid.initialize({
  er: {
    // Diagram padding
    padding: 20,
    
    // Layout direction: 'TB' | 'BT' | 'LR' | 'RL'
    layoutDirection: 'TB',
    
    // Min entity width/height
    minEntityWidth: 100,
    minEntityHeight: 75,
    
    // Entity spacing
    entityPadding: 15,
    
    // Stroke
    stroke: 'gray',
    fill: 'honeydew',
    
    // Font size
    fontSize: 12,
    
    // Use max width
    useMaxWidth: true
  }
});

Configuration API

Mermaid exposes several functions for working with configuration:

import {
  initialize,        // Set initial configuration
  getConfig,        // Get current configuration
  setConfig,        // Update current configuration  
  getSiteConfig,    // Get site-level configuration
  setSiteConfig,    // Set site-level configuration
  updateSiteConfig, // Update site-level configuration
  reset,            // Reset to site configuration
  defaultConfig     // Get default configuration
} from 'mermaid';

// Initialize (call once at startup)
mermaid.initialize({
  theme: 'dark',
  logLevel: 'error'
});

// Get current configuration
const config = getConfig();
console.log(config.theme); // 'dark'

// Update site config at runtime
updateSiteConfig({
  theme: 'forest'
});

// Reset to site config (clears directive/frontmatter overrides)
reset();

// Reset to specific config
reset(defaultConfig);

Avoid calling getConfig() repeatedly. Store the result in a variable and reuse it. The function creates a deep copy each time it’s called.

Configuration best practices

1. Initialize once

Call initialize() only once at application startup:

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

// Bad - don't re-initialize
mermaid.initialize({ theme: 'dark' });
// ... later ...
mermaid.initialize({ theme: 'forest' }); // Don't do this

2. Use updateSiteConfig for runtime changes

// Good
import { updateSiteConfig } from 'mermaid';
updateSiteConfig({ theme: 'forest' });

// Avoid
mermaid.initialize({ theme: 'forest' }); // Re-initializing

3. Prefer frontmatter over directives

Frontmatter is more readable and maintainable:

Versus:

4. Secure user-generated content

When rendering untrusted diagrams:

mermaid.initialize({
  securityLevel: 'strict',
  secure: [
    'secure',
    'securityLevel',
    'startOnLoad',
    'maxTextSize'
  ]
});

5. Validate configuration

Mermaid silently ignores invalid configuration keys. Use TypeScript for type safety:

import type { MermaidConfig } from 'mermaid';

const config: MermaidConfig = {
  theme: 'dark',
  // TypeScript will catch typos
  // them: 'dark', // Error: Object literal may only specify known properties
};

mermaid.initialize(config);

Common configuration patterns

Dark mode

mermaid.initialize({
  theme: 'dark',
  themeVariables: {
    darkMode: true,
    background: '#1e1e1e',
    primaryColor: '#4dabf7',
    secondaryColor: '#748ffc',
    tertiaryColor: '#f783ac',
    primaryTextColor: '#fff',
    secondaryTextColor: '#fff',
    tertiaryTextColor: '#fff',
    lineColor: '#f8f8f8',
    textColor: '#f8f8f8'
  }
});

High-contrast

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#000',
    primaryTextColor: '#fff',
    primaryBorderColor: '#fff',
    lineColor: '#000',
    secondaryColor: '#fff',
    tertiaryColor: '#808080',
    background: '#fff',
    textColor: '#000',
    fontSize: '18px'
  }
});

Compact diagrams

mermaid.initialize({
  flowchart: {
    padding: 5,
    nodeSpacing: 30,
    rankSpacing: 30
  },
  sequence: {
    actorMargin: 25,
    boxMargin: 5,
    noteMargin: 5
  }
});

Hand-drawn style

mermaid.initialize({
  look: 'handDrawn',
  theme: 'neutral',
  flowchart: {
    curve: 'cardinal'
  }
});

Deprecated options

Some configuration options have been deprecated. Mermaid will log warnings when these are used.

// Deprecated
{
  flowchart: {
    htmlLabels: true // Use global htmlLabels instead
  },
  lazyLoadedDiagrams: [], // Use registerExternalDiagrams instead
  loadExternalDiagramsAtStartup: false // Use registerExternalDiagrams instead
}

// Preferred
{
  htmlLabels: true
}

Next steps

Theming

Customize colors and visual appearance

Initialization

Learn about initialization patterns

API reference

Complete configuration API reference

Security

Learn about security best practices