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.

The direction statement belongs inside the subgraph block. For example, an overall flowchart TB can contain direction LR for a horizontal processing stage. External edges can still influence the result, so subgraph direction is a layout preference rather than an absolute coordinate system.

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.

When Subgraph Direction Is Ignored

A subgraph's direction can be overridden by its connections to the outer graph. For example, an edge from a node inside the subgraph to an external node gives the layout engine an additional rank constraint. The result may follow the parent flow more strongly than the requested internal direction.

When that happens:

1. Check whether internal nodes connect directly to external nodes.
2. Route external relationships through one clearly named boundary node where practical.
3. Reduce crossing edges before adding layout workarounds.
4. Preview at the page width your readers will use.

The direction declaration can still be valid even when the visual result is not absolute. Mermaid optimizes the complete graph rather than positioning each subgraph independently.

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.

Flowchart Direction FAQ

What is flowchart TB in Mermaid?

It creates a flowchart whose main direction runs from top to bottom. flowchart TD is an equivalent spelling.

Is graph TD different from flowchart TB?

For ordinary Mermaid flowcharts, graph and flowchart introduce the same diagram type, while TD and TB both mean top to bottom. Prefer flowchart TB in new documents for clarity.

Why is my flowchart LR still partly vertical?

LR controls the overall rank direction, not the exact coordinates of every node. Branches, long labels, subgraphs, and crossing edges can still create vertical placement inside a left-to-right diagram.