Mermaid Flowchart Direction: TB, TD, LR, RL, and BT Explained

The same Mermaid flowchart can tell a clearer story simply by changing its direction. A deployment pipeline usually reads naturally from left to right. An approval hierarchy may work better from top to bottom. Mermaid lets you choose the initial layout with a short direction code after flowchart.

The Five Direction Codes

Code	Meaning	Typical use
TB	Top to bottom	Processes, hierarchies
TD	Top down, equivalent to TB	Same uses as TB
BT	Bottom to top	Escalation or dependency views
LR	Left to right	Pipelines, request flows
RL	Right to left	Reverse flows, rollback paths

TB and TD are aliases. Pick one convention and use it consistently across a documentation set.

Top-to-Bottom Flowchart

Top-to-bottom layouts fit narrow reading columns because the diagram grows vertically. They work well for decision trees, onboarding steps, and approval processes.

Left-to-Right Flowchart

Change only the direction code:

LR makes a sequence resemble a timeline or pipeline. It is often the best first choice for architecture flows, but a long chain can become too wide on mobile.

Bottom-to-Top and Right-to-Left

Less common directions can make a specific relationship easier to understand:

Here, raw inputs rise toward a summarized view. A right-to-left chart can represent a rollback or reverse-data path:

Direction should reinforce the idea, not surprise the reader. If a reverse layout needs a paragraph of explanation, a conventional direction may be clearer.

Direction Inside Subgraphs

Large diagrams often group nodes:

The outer graph moves left to right while the platform group requests a top-to-bottom internal layout. Mermaid's layout engine may not honor an internal direction when nodes inside a subgraph connect to nodes outside it in certain ways. Treat subgraph direction as a layout instruction to test, not a guarantee that overrides every edge constraint.

Why Changing Direction Sometimes Seems Ineffective

Mermaid uses a graph layout engine, not fixed coordinates. Direction establishes the overall rank flow, while edges, subgraphs, node sizes, and labels still influence placement. Two nodes may appear beside one another even in a vertical graph if the engine needs room for branches.

If the result is awkward:

1. Shorten long node labels.
2. Remove edges that duplicate an already obvious relationship.
3. Split one enormous diagram into an overview and detailed diagrams.
4. Keep the main path visually simple and move exceptions to branches.
5. Try TB for narrow pages and LR for wide screens.

Do not add invisible nodes or chains of dummy edges until you have simplified the real graph. Layout hacks make source harder to maintain and can behave differently after a Mermaid upgrade.

graph Versus flowchart

You may encounter older examples beginning with graph TD:

For ordinary flow diagrams, graph and flowchart are commonly used with the same direction codes. Prefer flowchart in new documentation because it states the diagram type clearly, then follow the conventions of the codebase when editing an existing file.

Choosing a Direction

Use the reader's path as the deciding rule:

• Choose TB for branching decisions and mobile-friendly documents.
• Choose LR for stages, pipelines, and system interactions.
• Use BT or RL only when reversal is part of the meaning.
• Use subgraph directions sparingly and verify the rendered result.

Open the Markdown in mdview.io to compare directions with the diagram inside its actual document. The best layout is not the one that fills the most space; it is the one that lets a reader predict where to look next.