Layout engines

​

Available layouts

​

Configuring layouts

​

Using frontmatter

​

Using initialization

import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  layout: 'elk',
});

​

Using directive (deprecated)

​

ELK (Eclipse Layout Kernel)

​

Features

• Multiple layout algorithms
• Node placement strategies
• Edge routing options
• Support for hierarchical structures

​

Configuration

mermaid.initialize({
  elk: {
    mergeEdges: false,
    nodePlacementStrategy: 'BRANDES_KOEPF',
    forceNodeModelOrder: false,
    considerModelOrder: 'NODES_AND_EDGES',
  },
});

​

ELK options

​

Node placement strategies

• BRANDES_KOEPF - Fast and produces good results for most diagrams
• LINEAR_SEGMENTS - Emphasizes straight line segments
• INTERACTIVE - Optimized for interactive diagrams
• SIMPLE - Simple placement algorithm

​

Example with ELK

​

Dagre

​

Features

• Fast performance
• Good for moderate complexity
• Layered layout algorithm
• Handles most common use cases

​

Configuration

mermaid.initialize({
  flowchart: {
    defaultRenderer: 'dagre',
  },
});

​

Example with dagre

​

Tidy tree

​

Features

• Optimized for tree structures
• Clean, organized layout
• Configurable spacing and orientation

​

Configuration

​

Example with tidy tree

​

Cose Bilkent

​

Features

• Handles cyclic graphs
• Force-directed positioning
• Natural-looking layouts
• Good for network diagrams

​

Example with cose-bilkent

​

Choosing the right layout

​

Use ELK when:

• Diagrams are large and complex
• You need fine-tuned control over layout
• Standard layouts don’t produce good results
• You have hierarchical structures with many levels

​

Use dagre when:

• Diagrams are small to medium sized
• Performance is important
• Diagrams are directed acyclic graphs
• You want the standard Mermaid look

​

Use tidy tree when:

• Diagrams are pure tree structures
• You want clean hierarchical layouts
• Parent-child relationships are clear
• You need predictable spacing

​

Use cose-bilkent when:

• Diagrams have cycles
• You want force-directed layouts
• Network topology is important
• Standard layouts create overlaps

​

Comparison example

​

Per-diagram configuration

// Global configuration
mermaid.initialize({
  layout: 'dagre',  // Default layout
});

​

Performance considerations

​

Layout engine performance

• Fastest: dagre
• Fast: tidy-tree
• Moderate: ELK
• Slower: cose-bilkent (for large graphs)

​

Optimization tips

• Use dagre for simple diagrams to maximize performance
• Switch to ELK only when needed for complex layouts
• Limit diagram size when using force-directed layouts
• Consider pre-calculating layouts for static diagrams

​

Troubleshooting

​

Overlapping nodes

• Try switching to ELK layout
• Increase diagram padding
• Adjust node placement strategy
• Simplify the diagram structure

​

Poor layout quality

• Experiment with different layout engines
• Adjust layout-specific configuration options
• Restructure your diagram for better flow
• Use subgraphs to organize complex sections

​

Slow rendering

• Switch to dagre if using ELK
• Reduce diagram complexity
• Split large diagrams into smaller ones
• Use lazy loading for multiple diagrams

​

Next steps