Mermaid flowchart sizing and layout: best practices

A Mermaid flowchart that looks perfect on your laptop might overflow on mobile, or sprawl across a page in print. Unlike hand-drawn diagrams, code-based flowcharts must scale. This guide covers sizing, aspect ratios, responsive rendering, and the layout algorithms that control how your diagram fits into real-world constraints.

Understanding Mermaid's layout engine

Mermaid uses Graphviz's layout algorithms by default. The algorithm chooses node positions and edge routing based on graph structure — you declare nodes and edges, the engine arranges them. For flowcharts, the TD (top-down) and LR (left-right) directives control overall orientation, but the engine's internal calculations determine spacing and nesting behavior.

flowchart TD
    A[Start] --> B{Check\nCondition}
    B -->|True| C[Process A]
    B -->|False| D[Process B]
    C --> E[End]
    D --> E

Controlling diagram dimensions

The maxWidth directive

By default, Mermaid renders flowcharts at whatever width the layout engine calculates. To cap width, use the config directive:

%%{init: {'flowchart': {'maxWidth': 300}}}%%
flowchart LR
    A[User Input] --> B[Validate]
    B --> C[Save to DB]
    C --> D[Return Result]

Setting maxWidth forces taller diagrams — the layout engine reflows to fit the constraint. This is essential for mobile or sidebar layouts.

Nesting and subgraph sizing

Subgraphs affect layout. A deep nesting of subgraphs can double the diagram height. Keep subgraph depth shallow:

flowchart TD
    subgraph Frontend["Frontend Layer"]
        A[Web UI]
        B[Mobile App]
    end
    subgraph Backend["Backend Layer"]
        C[API Gateway]
        D[Service]
    end
    A --> C
    B --> C
    C --> D

Choosing the right direction

• TD (top-down) works for hierarchies, decision trees, and workflows with clear start/end points. Naturally tall, good for desktop.
• LR (left-right) works for swimlanes, sequential processes, and architectures. Good for wide screens and horizontally-scrolled views.
• TB (top-to-bottom, alias for TD) and BT (bottom-to-top) are less common but useful for reversed hierarchies.

Mismatched direction and content creates sprawl. A sequential workflow forced into TD creates unnecessary height; a decision tree in LR may need horizontal scrolling.

flowchart LR
    A[Request] -->|Send| B[API]
    B -->|Process| C[Handler]
    C -->|Query| D[(Database)]
    D -->|Return| C
    C -->|Respond| B
    B -->|Return| A

Aspect ratio and responsive design

For HTML/web pages

Wrap Mermaid in a container with overflow: auto and a reasonable min-width. Let the browser scroll if needed, but set a default height:

<div style="overflow: auto; max-height: 600px; border: 1px solid #ccc;">
  <div class="mermaid">
    flowchart LR
      ...
  </div>
</div>

For documentation

When embedding in Markdown (GitHub, GitLab, Notion):

• Keep diagrams under 15–20 nodes for readability on small screens.
• Use LR for wider screens, TD for narrower docs.
• Test on mobile — most platforms respect the viewport.

For exports/images

If you export a diagram to PNG or SVG:

• Specify scale in the config to upscale without pixelation.
• Set a fixed width and let the aspect ratio adapt:

%%{init: {'flowchart': {'maxWidth': 800, 'scale': 2}}}%%
flowchart TD
    ...

Balancing horizontal and vertical spread

When a single node has many outgoing edges, the layout engine spreads them horizontally. To prevent wide diagrams, use intermediate nodes:

Before (wide):

flowchart TD
    A[Event] --> B[Handler 1]
    A --> C[Handler 2]
    A --> D[Handler 3]
    A --> E[Handler 4]

After (taller but narrower):

flowchart TD
    A[Event] --> F[Router]
    F --> B[Handler 1]
    F --> C[Handler 2]
    F --> D[Handler 3]
    F --> E[Handler 4]

Label length and node sizing

Long node labels increase width. Abbreviate or split across lines using \n:

flowchart TD
    A["Validate\nEmail"] --> B["Check\nDatabase"]
    B --> C["Send\nConfirmation"]

Mermaid auto-sizes nodes to fit text, so keeping labels short reduces layout pressure.

Performance considerations for large diagrams

As diagram complexity grows, rendering time increases. A few tips:

• Avoid deeply nested subgraphs — each layer adds computational cost.
• Limit cross-edges — edges that connect distant parts of the graph force wider spacing.
• Group related nodes into subgraphs to reduce visual clutter and layout calculations.
• Test on lower-powered devices — a 200-node diagram may lag on mobile.

Testing your layout

Use the visual editor to test layouts interactively. Paste your Mermaid code and adjust:

1. Change the direction (TD ↔ LR).
2. Tweak maxWidth and observe reflow.
3. Add or remove subgraphs and watch spacing change.
4. Test on mobile by narrowing your browser window.

The editor renders in real-time, so you see the impact of every change immediately.

Common layout pitfalls

Problem	Cause	Fix
Diagram too wide	Many siblings or long labels	Add intermediate nodes or split labels with \n
Diagram too tall	Too many sequential nodes	Collapse into subgraphs or split into two diagrams
Confusing crossing edges	Poor node ordering	Reorder nodes or add subgraphs to separate concerns
Responsive overflow	No maxWidth or container constraint	Set maxWidth and test on mobile

FAQ

Can I set a fixed height for a flowchart? Mermaid doesn't have a direct maxHeight directive, but you can set height on the container element in HTML (style="height: 400px;"). The diagram will scroll if needed.

Should I use subgraphs for everything? No. Use subgraphs only when they represent a logical grouping. Too many subgraphs create noise and slow rendering.

How do I know if my diagram is too complex? If you can't describe it in one sentence, or if it needs more than 30–40 nodes, split it into two or three focused diagrams.

Try these techniques in the visual editor at /playground — adjusting layout in real-time beats guessing on paper.