Mermaid Block Diagram Tutorial: Layouts, Arrows & Real Examples (2026)

# Mermaid Block Diagram Tutorial: Layouts, Arrows & Real Examples

Mermaid's block diagram is one of the most underrated diagram types in the library. Introduced in Mermaid 10.9, it lets you arrange rectangular blocks in flexible grid layouts — perfect for system architecture, hardware schematics, memory maps, network zones, and any "boxes-and-lines" picture that doesn't fit neatly into a flowchart.

If you've ever fought with a flowchart trying to make it look like a *layout* instead of a *flow*, this is the diagram type you've been missing.

What Is a Mermaid Block Diagram?

A block diagram is a grid of blocks (rectangles) connected by arrows. Unlike flowcharts, blocks don't try to auto-layout based on connections — you control the columns and rows directly. That makes them ideal for diagrams where the *spatial arrangement itself* carries meaning, like:

- Microservice architectures

- CPU / memory / hardware layouts

- Network DMZ and security zones

- UI wireframes and dashboard regions

- Cloud account / VPC topologies

Basic Syntax

Every block diagram starts with the block-beta keyword:

block-beta
  columns 3
  A B C
  D E F

That single columns 3 declaration is the magic. It tells Mermaid to lay out everything in a 3-wide grid. Add more identifiers, and they wrap into new rows automatically.

Block Shapes

Just like flowcharts, blocks support multiple shapes via bracket syntax:

block-beta
  columns 4
  A["Rectangle"] B("Rounded") C(("Circle")) D{"Diamond"}
  E[("Cylinder")] F>"Flag"] G{{"Hexagon"}} H[/"Parallelogram"/]

Spanning Columns and Rows

This is where block diagrams pull ahead of flowcharts. Use block:id:width to make a block span multiple columns:

block-beta
  columns 3
  Header["Application Header"]:3
  Sidebar["Sidebar"] Main["Main Content"]:2
  Footer["Footer"]:3

That single diagram is a complete page layout in five lines of text. Try doing *that* cleanly in a flowchart.

Composite Blocks (Nested Groups)

Use the block:groupName syntax to create a container that holds other blocks:

block-beta
  columns 3
  block:Frontend
    Web["Web App"]
    Mobile["Mobile App"]
  end
  API["API Gateway"]
  block:Backend
    Auth["Auth Service"]
    Users["User Service"]
    Orders["Order Service"]
  end

Nested groups render as labeled containers with their children inside — exactly what you want for microservice or domain-driven architecture diagrams.

Adding Arrows

Connections work the same way they do in flowcharts:

block-beta
  columns 3
  A["Client"] space B["Load Balancer"] space C["Server"]
  A --> B
  B --> C

The space keyword inserts an empty cell so arrows have room to breathe. Use space:2 to skip multiple cells.

Styling Blocks

Block diagrams support the same style and classDef keywords as flowcharts:

block-beta
  columns 3
  A["Critical"] B["Healthy"] C["Warning"]
  style A fill:#ef4444,color:#fff,stroke:#991b1b
  style B fill:#22c55e,color:#fff,stroke:#15803d
  style C fill:#f59e0b,color:#fff,stroke:#b45309

For repeated styles, define a class once and reuse it:

block-beta
  columns 4
  classDef service fill:#3b82f6,color:#fff,stroke:#1d4ed8
  Web Auth Users Orders
  class Web,Auth,Users,Orders service

Real-World Example: AWS Architecture

Here's a production-style cloud architecture in Mermaid block syntax:

block-beta
  columns 5
  block:Edge:5
    CF["CloudFront CDN"] WAF["WAF"] R53["Route 53"]
  end
  ALB["Application Load Balancer"]:5
  block:Compute:3
    ECS1["ECS Task 1"]
    ECS2["ECS Task 2"]
    ECS3["ECS Task 3"]
  end
  block:Cache:2
    Redis["ElastiCache"]
    Mem["Memcached"]
  end
  RDS["RDS Postgres (Multi-AZ)"]:3 S3["S3 Bucket"]:2

Five rows, real components, zero drag-and-drop. And because it's plain text, you can diff it in pull requests, generate it programmatically, or paste it into a GitHub README and it just renders.

When to Use Block Diagrams vs Flowcharts

Common Pitfalls

• Forgetting columns N — without it, blocks stack vertically. Always declare your grid width.
• Spans that exceed columns — X:5 in a 3-column grid silently breaks layout. Match your spans to your grid.
• Old Mermaid version — block diagrams need Mermaid 10.9 or newer. If they don't render, upgrade your renderer (GitHub, Notion, and most modern tools already support them).
• Nested arrows — arrows between blocks inside different block: groups work, but routing can get messy. Keep critical arrows at the top level.

Conclusion

Block diagrams fill the exact gap that flowcharts and ER diagrams leave open: layout-first visualizations. Once you've drawn one architecture diagram in block-beta syntax, you'll wonder why you ever opened Lucidchart for the same job.

The whole syntax fits on a sticky note: columns N, blocks, optional spans with :N, and block:group...end for nesting. That's it. Everything else is the same Mermaid you already know.

Try the Mermaid block diagram syntax in our free editor →