Message types: solid arrow ->>, dashed arrow -->>, solid line ->, dashed line -->
Participants: participant, actor, aliases

Class diagrams

Relationships: inheritance <|--, composition *--, aggregation o--, association --, dependency ..>, realization ..|>
Members: attributes and methods with visibility (+ public, - private, # protected, ~ package)

ER diagrams

Cardinality: || (exactly one), o| (zero or one), }| (one or more), o{ (zero or more)
Line styles: solid --, dashed ..

Attributes: type, name, keys (PK, FK, UK), comments

State diagrams

Features: [*] start/end states, transition labels, state "name" as alias, composite states (state Parent { }), stereotypes (<<choice>>, <<fork>>, <<join>>)
Block diagrams

Features: columns N, column spanning (blockname:N), links between blocks, nested blocks
Git graphs

Directions: LR (default), TB, BT
Commands: commit (with id:, type:, tag:), branch (with order:), checkout/switch, merge, cherry-pick

Commit types: NORMAL (●), REVERSE (✖), HIGHLIGHT (■)

Config: %%{init: {"gitGraph": {"mainBranchName": "master"}}}%%

Gantt charts

Design │ Wireframes │░░░░░░░░░░░░░ Prototypes │ ▓▓▓▓▓▓▓▓▓▓▓▓▓ Development │ Frontend │ ██████████████████████████████ Backend │ ███████████████████████████████████████████████ └┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬ Jan 01 Jan 11 Jan 21 Jan 31 Feb 10 Feb 20 Mar 01

Tasks: done, active, crit, milestone tags, after id dependencies, durations in Mermaid's units (30d, 2w, 3M, 1.5h, 45m, 1.2s, 406ms)

Time scales: any span from years to milliseconds. dateFormat YYYY-MM-DD HH:mm keeps the time of day, dateFormat x and X read Unix milliseconds and seconds, axisFormat %H:%M (or %S.%L) labels the axis, and tickInterval 6hour places the ticks

Pie charts
Yes, the syntax says pie. No, we don't draw a circle. I know. Have you ever tried to read a pie chart made of █ and ▓? Exactly. We render them as horizontal bar charts instead.

Features: title, showData (display raw values), %% comments

Treemaps

Features: nested sections via indentation, "label": value syntax, proportional sizing, %% comments
Mindmaps

Features: indentation-based nesting, automatic overflow to the left when many children, rounded/sharp/ASCII branch characters, Mermaid shape markers stripped ((round), [square], {{hexagon}}, )cloud()
XY charts

35 │ ████ │ ████ │ ▄▄▄▄ ████ 28 │ ████ ████ │ ▄▄▄▄ ████ ████ │ ████ ████ ████ 21 │ ████ ▄▄▄▄ ████ ████ │ ▄▄▄▄ ████ ████ ████ ████ │ ████ ████ ████ ████ ████ 14 │ ████ ████ ████ ████ ████ │████ ████ ████ ████ ████ ████ │████ ████ ████ ████ ████ ████ 7 │████ ████ ████ ████ ████ ████ │████ ████ ████ ████ ████ ████ │████ ████ ████ ████ ████ ████ 0 └──┬─────┬─────┬─────┬─────┬─────┬─ Jan Feb Mar Apr May Jun

Features: bar charts, line charts, bar+line combos, horizontal orientation (xychart horizontal), axis labels, xychart and xychart-beta keywords, rounded/sharp line corners, JSON ingest

User journeys

● Cat ◆ Me

╭───────────── Go to work ──────────────╮ ╭───────── Go home ───────────╮

╭◆─────────╮ ╭◆────────────╮ ╭●◆───────╮ ╭◆──────────────╮ ╭◆─────────╮ ─│ Make tea │─│ Go upstairs │─│ Do work │────│ Go downstairs │─│ Sit down │────► ╰──────────╯ ╰─────────────╯ ╰─────────╯ ╰───────────────╯ ╰──────────╯ 😄 😐 😞 😄 😄

Features: sections, satisfaction scores (😞-😄), multi-actor support with distinct symbols (●◆■▲), rounded/sharp/ASCII corners

Packet diagrams

Features: bit-aligned field layouts, boundary numbers, auto-increment (+N) syntax, separated boxes per row, truncated label legend with bit ranges, packet and packet-beta keywords
CLI options
| Flag | Description |
|------|-------------|
| --ascii | ASCII-only output (no Unicode box-drawing) |
| --theme NAME | Color theme (requires pip install termaid[rich]). Use --themes to list |
| --themes | List all available color themes |
| --demo [TYPE] | Render sample diagrams (all, flowchart, sequence, mindmap, etc.) |
| --padding-x N | Horizontal padding inside boxes (default: 4) |
| --padding-y N | Vertical padding inside boxes (default: 2) |
| --gap N | Space between nodes (default: 4). Use 1 or 2 for compact diagrams |
| --inline-edge-labels | Attach flowchart labels directly to their edges |
| --width N | Max output width. Re-renders with smaller gap/padding, then wraps labels, if exceeded |
| --strict-width | Exit with status 2 instead of a warning when the output is still wider than --width |
| --max-height ROWS | Exit with status 2 when the output has more than ROWS lines (a check, not a fitting target) |
| --no-auto-fit | Disable automatic compaction when diagram exceeds terminal width |
| --sharp-edges | Sharp corners on edge turns instead of rounded |
| -o FILE | Write output to file instead of stdout |
| --show-ids | Show node IDs alongside labels for debugging (e.g. myId: My Label) |
| --json TYPE | Pipe JSON/tabular data and render as treemap, pie, mindmap, flowchart, or xychart |
| --markdown | Read a Markdown document and draw each mermaid code block in place; other text passes through. A block that cannot be drawn is kept as source, with a warning |
| --claude-hook | Run as a Claude Code MessageDisplay hook: read one batch of a reply as JSON on stdin and draw its mermaid blocks in place (see Claude Code) |
| --tui | Interactive TUI viewer (requires pip install termaid[tui]) |
| --format FORMAT | text (default) or styled-json: one JSON document of text chunks tagged with style keys (see Editor and tool integration) |
| --diagnostics-format FORMAT | text (default) or json: print each error and warning on stderr as one JSON line |

Python API
render(source, ...) -> str

Render a Mermaid diagram as a plain text string. Auto-detects diagram type.
render_rich(source, ..., theme="default") -> rich.text.Text

Render as a Rich Text object with colors. Requires pip install termaid[rich].

render_styled(source, ...) -> dict

Render as theme-independent styled chunks, the same document that --format styled-json prints (see Editor and tool integration).

MermaidWidget

A Textual widget with a reactive source attribute. Requires pip install termaid[textual]. Updates live when you change the source property.

class MyApp(App): def compose(self): yield MermaidWidget("graph LR\n A --> B")

## Themes

11 built-in themes for --theme / render_rich(). Run termaid --themes to list them.

Text themes (foreground colors only):
| Theme | Colors | Description |
|-------|--------|-------------|
| default | !#00FFFF !#FFFF00 !#FFFFFF | Cyan nodes, yellow arrows, white labels |
| terra | !#D4845A !#E8A87C !#F5E6D3 | Warm earth tones (browns, oranges) |
| neon | !#FF00FF !#00FF00 !#00FFFF | Magenta nodes, green arrows, cyan edges |
| mono | !#FFFFFF !#AAAAAA !#666666 | White/gray monochrome |
| amber | !#FFB000 !#FFD080 !#FFD580 | Amber/gold CRT-style |
| phosphor | !#33FF33 !#66FF66 !#AAFFAA | Green phosphor terminal-style |

Solid themes (filled backgrounds with foreground colors):
| Theme | Colors | Description |
|-------|--------|-------------|
| gruvbox | !#282828 !#FABD2F !#FE8019 | Gruvbox dark palette |
| monokai | !#272822 !#F92672 !#A6E22E | Monokai dark with pink/green accents |
| dracula | !#282A36 !#BD93F9 !#50FA7B | Dracula purple/pink/green palette |
| nord | !#2E3440 !#88C0D0 !#A3BE8C | Nord muted blue/cyan arctic palette |
| solarized | !#002B36 !#268BD2 !#B58900 | Solarized dark blue/yellow/cyan |

Optional extras

## Claude Code
Claude draws Mermaid diagrams all the time. With the termaid plugin they show up
in the terminal as diagrams instead of code fences, while Claude keeps seeing the
Mermaid source. One command on Claude Code 2.1.275 or later:

On older versions, add the marketplace first with /plugin marketplace add fasouto/termaid
and then /plugin install termaid@termaid. The plugin needs the termaid command on
your PATH (brew install termaid or uv tool install termaid). It adds:

a MessageDisplay hook that runs termaid --claude-hook on each reply and draws its
  mermaid blocks in place. It only changes what you see. The transcript keeps the source,
  and if termaid is missing or fails, Claude Code shows the original text.
a /termaid:mermaid skill for explicit requests, such as rendering a file or the
  diagrams in a PR description.
Without the plugin, the same hook works from .claude/settings.json:

For headless use, pipe the reply through termaid --markdown:

## Editor and tool integration

Editor plugins and other tools that run termaid as a subprocess can ask for
structured output instead of terminal text.
--format styled-json prints the diagram as one line of JSON. Each line of the
diagram is a list of chunks, and each chunk is a run of text with one style key.
For graph LR; A-->B with --padding-x 1 --padding-y 0, wrapped here at each
diagram line:

Joining the chunk texts of each line gives exactly the text output, fitted to
--width the same way. The tool picks the colors. Style keys name the role of
the cells (node, edge, arrow, label, edge_label, subgraph,
section:N, and so on). Flowcharts also carry class:<name>,
nodestyle:<id> and linkstyle:<index>, so a tool can apply the diagram's own
classDef, style and linkStyle colors. termaid ignores --theme here and
rejects --tui, --markdown and --claude-hook together with this format.

--diagnostics-format json prints each error and warning on stderr as one JSON
line, with a stable code to branch on:

Limitations