Mermaid Layout Engines

To control how diagrams position, space, and organize shapes on the screen, Mermaid relies on specialized layout engines.

While traditional flowcharts automatically map layouts via graph algorithms, modern Mermaid versions allow you to change engines or use alternate syntax configurations to achieve cleaner layouts.

The Core Layout Engines

Mermaid leverages different open-source rendering libraries under the hood depending on the diagram type:

Engine	Default Diagram Types	Layout Strategy / Behavior
Dagre	flowchart, graph, classDiagram	Directed graph layout. Focuses on minimizing crossed lines and organizing nodes hierarchically along a clear structural path (TD, LR, etc.).
D3-Gantt	gantt	Time-series layout. Organizes elements horizontally along a strict date/time coordinate grid axis.
Elk (Beta)	flowchart (with config)	Advanced layout engine designed for large, highly complex, or nested graphs. Prevents overlapping subgraphs better than Dagre.
Hand-Drawn (Rough.js)	Any supported chart	Applies a sketch-like, organic aesthetic overlay onto the output generated by the primary structural layout engine.

Switching to the Advanced ELK Engine

If you are building massive flowcharts and notice that subgraphs are overlapping or arrows are crossing awkwardly, you can force Mermaid to use the ELK renderer instead of Dagre by passing an initializer header:

---
config:
  layout: elk
---
flowchart LR
    subgraph Alpha
        A --> B
    end
    subgraph Beta
        C --> D
    end
    A --> C

Try this code ❯

Layout Control Strategies (Hacking the Engines)

Because you cannot manually drag-and-drop nodes in text-based diagramming, you must use precise syntax tricks to guide the engine's layout math.

Strategy A: Invisible Lines (~~~)

If the Dagre engine places two nodes too close together or stacks them vertically when you want them side-by-side, use an invisible connection line to force spacing:

flowchart TD
    A[Top Node] --> B[Left Action]
    A --> C[Right Action]
    
    %% Forces spacing between Left and Right choices without a visible arrow
    B ~~~ C

Try this code ❯

Strategy B: Subgraph Orientation Overrides

You can break the global layout constraint (e.g., a Top-Down layout) inside specific sections by giving a local direction instruction to a subgraph wrapper:

flowchart TD
    %% Main canvas flows Top-to-Bottom
    Start[Initialization] --> DataStream
    
    subgraph DataStream [Internal Processing Tiers]
        direction LR
        %% Inside this box, elements flow cleanly Left-to-Right
        Ingest --> Parse --> Cache
    end
    
    DataStream --> End[Terminal State]

Try this code ❯

Activating Hand-Drawn Sketch Mode

If you want to bypass rigid mechanical structures entirely and give your diagram a custom hand-drawn mockup aesthetic, you can switch the underlying rendering variables to handDrawn inside your config metadata:

---
config:
  look: handDrawn
  theme: forest
---
flowchart LR
    Idea[Concept Sketch] --> Prototype[Working Model]

Try this code ❯

More Examples

1. Dagre — Default

Dagre is commonly used for flowcharts.

---
config:
  flowchart:
    defaultRenderer: dagre
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Try this code ❯

2. ELK

ELK can be useful for more complex diagrams and provides additional layout options.

---
config:
  flowchart:
    defaultRenderer: elk
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]
    A --> D[Alternative]
    D --> C

Try this code ❯

3. Choosing the Layout Engine

You can specify the renderer in the Mermaid configuration:

---
config:
  flowchart:
    defaultRenderer: elk
---
flowchart LR
    A[Client] --> B[Server]
    B --> C[Database]

Try this code ❯

Common layout/rendering options

Engine	Typical use
`dagre`	Standard flowcharts
`elk`	Complex flowcharts and more advanced layouts

Simple rule: Start with Dagre. If a complex flowchart doesn't arrange nodes the way you want, try ELK.