Skip to content
MermaidViewer

Software diagram

Mermaid block diagram

Mermaid block diagram syntax for columns, blocks and layout, with a layered system example.

By MermaidViewer editorsPublished Updated

Basic block diagram example

Basic block diagram example diagram
mermaid
block
    columns 3
    Client["Browser"]:3
    space:3
    Web["Web server"] API["API"] Worker["Worker"]
    space:3
    DB[("PostgreSQL")]:2 Cache["Redis"]
    Client --> API
    API --> DB
    Worker --> DB
    API --> Cache
Open in the live editor

Block diagrams give you control over layout. Instead of letting Mermaid position everything automatically, you define a grid with a number of columns and place blocks in it — useful when the spatial arrangement carries meaning.

They work well for system overviews, hardware diagrams, network layers and any picture where you want boxes aligned in rows and columns.

When to use a block diagram

  • High-level system overviews
  • Layered architectures
  • Hardware and network diagrams
  • Dashboards and page layouts

Block Diagram syntax reference

SyntaxWhat it does
block (or block-beta)Start a block diagram.
columns 3Number of columns in the grid.
a["Label"]A block with a label; shapes like flowchart nodes.
a:2Block spanning two columns.
space / space:2Empty cell(s) for spacing.
block:group ... endNested block containing other blocks.
a --> bArrow between blocks.

Block Diagram examples

Layered architecture

Full-width layers stacked vertically.

Layered architecture diagram
mermaid
block
    columns 1
    UI["Presentation layer"]
    App["Application layer"]
    Domain["Domain layer"]
    Infra["Infrastructure layer"]
Open in the live editor

You set the rows and columns yourself. A mermaid block diagram places boxes on a grid. A flowchart will shuffle those boxes whenever you add an arrow. Use blocks when the rows themselves mean something, such as layers of a system.

Columns and labels

block-beta opens the diagram. columns 1 means one box per row, so the next boxes stack. web["Web"] is a block. The id is web and the label is Web. With columns 1, the order of the lines is the order down the page. That's the feature. You're writing the layout, not describing a graph and hoping.

A larger columns number fills a row left to right and then wraps. columns 3 with four blocks puts three on the first row and one on the second. If that wrap surprises you, you wanted another row break, which in this simple form means a different column count or a spacer you have already planned. Start with columns 1 until the stack is right, then widen.

Arrows are allowed, web --> api, and they're optional. On a layered picture the vertical order already says "above talks to below." Add an arrow when the neighbor isn't obvious from the stack. Skip arrows when every neighbor is connected, or the grid disappears under the lines.

Labels stay short. The block is a cell, not a paragraph. Put the explanation in the doc.

Worked example

A small app is three layers. The page is on top, the API is in the middle, and the database is at the bottom.

Mermaid diagram
mermaid
block-beta
    columns 1
    web["Web"]
    api["API"]
    db["Database"]
Open in the live editor

columns 1 is the whole layout decision. Web can't drift to the side of API, because there's no side. The stack reads as a dependency direction even without arrows: the page calls the API, the API calls the database. If your real system lets the page call the database too, the stack is now a lie, and you should add web --> db or stop using a single column.

Renaming api["API"] to api["Public API"] doesn't move the box. The id stays api, which matters once arrows point at it. Adding a cache as a fourth block puts it under the database, which is probably wrong. With one column, position is list position. Insert the cache line where the layer actually sits.

This diagram won't show request order. It shows arrangement. If you need the page to call the API and then the API to write, pair it with a sequence diagram and let this picture stay the map of layers. A reader should be able to point at a row and say which tier it's. If they can't, the column count is hiding the story.

When this is the wrong diagram

A flowchart is the better picture when you want automatic layout and the branches are decisions. An architecture diagram is the better picture when the boxes should be cloud icons inside a network group. Use a block diagram when a row or a column is the meaning.

Common mistakes

  1. Picking columns 3 and then wondering why the fourth block wrapped to the next row. The column count is the row width. columns 1 stacks.
  2. Changing a label by editing the id, then leaving arrows pointed at the old id. The id and the label are different. api["API"] keeps the id stable.
  3. A sentence inside the quotes. The cell can't hold a paragraph. Shorten the label and explain it underneath the figure.
  4. An arrow between every pair, so the grid you set up is hidden. Add an arrow only where the stack doesn't already show the relationship.

Where to go next

The AI block diagram generator will stack components from a short description. Adjust columns in the editor and watch the wrap, and the cheat sheet has the block line. The system layers template is a wider grid if one column is too plain for your overview.

Columns are a reading order

A block diagram is a stack of boxes in columns. The left column is what the reader sees first. Put the client there and the database further right, or the opposite if you are drawing from the data outward, and then stay consistent. A box that spans columns is a layer, not a service that happens to have a long name.

Labels are the thing in the box, not a sentence about the thing. If you need a protocol, put it on the arrow between blocks or in the prose. The system layers template is a three-tier example you can rename.

A generator-style walkthrough is the block diagram generator post, and several grids you can paste are the mermaid block-beta examples.

Tips and best practices

  • Sketch the grid first — decide how many columns you need and which blocks should span.
  • Use space blocks to create breathing room between rows.
  • Prefer flowcharts when you want automatic layout and blocks when position matters.

Generate a block diagram with AI

Not sure where to start? Describe what you need and the AI block diagram generator writes the Mermaid code for you. Try prompts like:

  • “Smart home system components”
  • “Three-tier web application”
  • “CPU and memory hierarchy”

Block Diagram templates

Block Diagram FAQ

How is a block diagram different from a flowchart?

A flowchart is laid out automatically, while a block diagram lets you choose the number of columns, spans and empty spaces so blocks appear exactly where you want them.

Is it block or block-beta?

Newer Mermaid versions accept block; older versions need block-beta. MermaidViewer supports both.