MermanDraw
Open Editor

Mermaid guide

Mermaid Block Diagram: Columns, Block Widths, Spacing, and Arrows

The block diagram is a grid: you set the number of columns, then list blocks in reading order and Mermaid fills rows. Blocks can span several columns, space leaves a cell empty, and arrows connect blocks by ID. The result is the classic boxes-and-arrows architecture sketch, without a layout engine deciding placement for you.

Reach for it when a flowchart's automatic layout keeps moving the boxes you care about. Block diagrams are predictable: what you write is where it lands.

  • high-level architecture
  • system block diagrams
  • service grouping
  • context maps

Example

Mermaid Block example

Frontend
(Astro)

API
(Hono)

Storage
(D1/R2)

KV Cache

CDN
(Cloudflare)

Pages
Functions

Workers
Cron

block-beta
    columns 3
    A["Frontend
(Astro)"] B["API
(Hono)"] C["Storage
(D1/R2)"]
    space D["KV Cache"] space
    E["CDN
(Cloudflare)"] F["Pages
Functions"] G["Workers
Cron"]
    A --> B
    B --> C
    B --> D
    E --> A
    F --> B
    G --> C
Open in editor → Cheatsheet →

Syntax

Grid and widths

block-beta
    columns 3
    Frontend API Database
    space:3
    CDN:2 Cache
    Frontend --> API
    API --> Database
    API --> Cache
Grid and widths — Mermaid block

Frontend

API

Database

CDN

Cache

columns N sets the grid. Name:2 makes a block two columns wide; space:3 skips three cells.

Try this snippet →

Labels, shapes, nesting

block-beta
    columns 2
    block:group:2
        columns 2
        a["App server"] b[("Postgres")]
    end
    c(["Load balancer"]) d{{"Queue"}}
    c --> a
Labels, shapes, nesting — Mermaid block

App server

Postgres

Load balancer

Queue

Flowchart shape wrappers work on blocks. A block:id ... end pair nests a sub-grid with its own columns.

Try this snippet →

Styling

block-beta
    columns 2
    A B
    style A fill:#e0e7ff,stroke:#4338ca
    classDef db fill:#fef3c7
    class B db
Styling — Mermaid block

A

B

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • More blocks in a row than columns allows and expecting them to stay on one line.

    Fix: Mermaid wraps to the next row. Raise columns or use space to pad.

  • Arrow between blocks that were never declared.

    Fix: Every ID in an arrow must appear as a block first.

  • Writing block without -beta.

    Fix: The keyword in Mermaid 11 is block-beta.

Real-world examples

Complete, copy-ready blocks for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

When should I use a block diagram instead of a flowchart?

When placement matters more than flow: a layered architecture, a UI wireframe, a hardware board. For processes with branching, stay with a flowchart.

Can arrows have labels?

Yes: A -- "HTTPS" --> B.