Mermaid Block Diagram Tutorial: Precise Grid Layouts with block-beta
When you want blocks in a deliberate grid rather than an auto-arranged graph, Mermaid's block-beta gives you column control, spanning widths, and nesting.
Most Mermaid diagrams let an automatic layout engine decide where things go, which is usually what you want - but sometimes you need deliberate control over the grid. A memory map, a systems schematic, a layered architecture where the arrangement itself carries meaning: these call for blocks placed in specific columns and rows, with some blocks spanning wider than others. Mermaid's "block-beta" diagram is built for exactly this, giving you a column-based grid where you control the structure directly.
This guide covers the block-beta syntax - columns, block widths, nesting, and the arrows that connect blocks - with examples for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered diagram is fully editable in Atlas Diagram Studio at /diagrams, where you can fine-tune anything the grid did not get exactly right. When your layout is more free-form and you would rather not manage a grid, the flowchart maker at /diagram-tools/flowchart-maker and the AI diagram generator at /diagram-tools/ai-diagram-generator handle auto-arranged diagrams instead.
Columns and basic blocks
A block diagram starts with "block-beta", and the key layout control is the "columns" keyword, which sets how many columns the grid has - "columns 3" creates a three-column grid. Blocks are then listed by their identifiers, and they fill the grid left to right, top to bottom, wrapping to the next row when a row is full. A bare identifier like "a" creates a block labeled "a"; wrapping text in brackets, as in 'a["Web Server"]', gives it a display label distinct from its id.
The grid model is what makes block-beta different from a flowchart. In a flowchart you declare connections and the engine positions nodes; in a block diagram you declare positions via the column structure and the fill order. This is more work when you want automatic layout, but it is exactly the control you need when the spatial arrangement is part of the message - when "these three sit in a row above that one" is information, not just aesthetics.
Widths, nesting, and arrows
Block-beta's real expressiveness comes from spanning widths and nested blocks, which let you build non-uniform grids and grouped structures. The bullets below cover the constructs that give you that control.
- Set the grid width with "columns 3" near the top of the diagram.
- Make a block span multiple columns with the colon syntax: "a:2" makes block a two columns wide.
- Give a block a display label with brackets: 'db[("Database")]' for a cylinder shape.
- Insert an empty spacer with "space", or span it with "space:2" to push blocks into position.
- Nest a group with "block:group" ... "end", which contains its own blocks and can have its own columns.
- Connect blocks with arrows just like a flowchart: "a --> b" or labeled 'a -- "sends" --> b'.
- Apply shapes and styles to blocks using the same shape delimiters and "style" directives as flowcharts.
Composing a deliberate layout
Building a good block diagram is an exercise in thinking about the grid before you type. Decide how many columns your structure needs, then work row by row, using spanning widths where a block should be wider and "space" blocks where you need a gap to align things. Because blocks fill in order, the sequence in which you list them is the layout, so reading your source top to bottom should trace the grid left to right and down - a useful check that the text matches the intended picture.
Nesting is the tool for grouping. A "block:group ... end" wraps a set of related blocks in a container that itself occupies a cell in the parent grid and can define its own internal columns. This lets you build layered diagrams - a container of frontend blocks above a container of backend blocks - where each layer is a tidy sub-grid. When the grid gets fiddly, remember that the output opens in Atlas Diagram Studio at /diagrams, where nudging a block or connection by hand is often quicker than wrestling the syntax for a pixel-perfect result.
Block diagram versus flowchart
The choice between block-beta and a flowchart comes down to who decides the layout. Use a flowchart when the relationships matter most and you are happy to let the engine arrange the nodes - most process and logic diagrams fit this. Use a block diagram when the spatial arrangement itself is meaningful and you want to place things in a specific grid: hardware schematics, memory layouts, layered system pictures, and dashboards of labeled regions. The extra layout effort of block-beta only pays off when position carries information.
Both are Mermaid, so you can mix them in a documentation set and author both in the same editor. Start in the Mermaid editor at /diagram-tools/mermaid-editor, and bring the result into Atlas Diagram Studio at /diagrams for polish. For the automatic-layout diagrams and the full language, see the complete Mermaid guide at /guides/mermaid-js-complete-guide, and for turning a described layout into a starting diagram, the guide on text-to-diagram at /guides/text-to-diagram-with-ai.