Mermaid code in Whimsical

Mermaid is a text-based syntax for describing diagrams in code.

Whimsical turns Mermaid code into editable diagrams on your board, from flowcharts and sequence diagrams to kanban boards and architecture diagrams. Many of them turn back into Mermaid when you need the code.

Where Mermaid works in WhimsicalCopied!Link to this section

  • Paste onto a board. Copy Mermaid code from anywhere, like docs, GitHub or an AI chat, and hit Command + V (Mac) or Control + V (PC) on a board. You get editable shapes and connectors, not a picture.
  • Paste into a doc. Paste Mermaid into a doc, on its own, in a ```mermaid code block or inside a longer answer from an AI chat. Each diagram becomes a board nested in the doc. Undo once to turn it back into code. Mermaid in a doc's code blocks also gets syntax highlighting.
  • AI and MCP. The in-app AI and the Whimsical MCP (in Claude, ChatGPT and the desktop app) draw diagrams from Mermaid too, so what they make matches what you'd get from pasting.
  • Copy as Mermaid. Select a diagram, right-click and choose Copy as… → Mermaid to take it back out as code.

Supported diagram typesCopied!Link to this section

Start your code with any of these keywords. Each type becomes native Whimsical shapes, tables or stacks that you can edit like anything else on the board.

  • flowchart or graph - Shapes and connectors, with subgraphs as groups
  • swimlane-beta - A flowchart whose top-level subgraphs become lanes
  • sequenceDiagram - A sequence diagram with notes, frames and activations
  • stateDiagram-v2 - States, start and end dots, choices, forks, composite states and notes
  • erDiagram - A table per entity, joined by crow's foot connectors
  • classDiagram - A table per class
  • requirementDiagram - A table per requirement and element
  • C4Context, C4Container and the other C4 diagrams - People, systems, containers and components inside their boundaries
  • architecture-beta - Each service as its icon, in dashed groups
  • block-beta - Blocks, groups and block arrows on the grid you write
  • usecase-beta - Actors as figures and use cases as ellipses inside their system boundaries
  • eventmodeling - Frames in time order, each in the lane and color of its kind
  • timeline - Periods along arrows, with their events under them
  • mindmap - A Whimsical mind map
  • kanban - A stack per column, with its cards in it

FlowchartsCopied!Link to this section

Pasted flowcharts come out much closer to how Mermaid draws them:

  • Plain text or code blocks. Paste a chart as plain text or inside a ```mermaid code block, frontmatter included. A frontmatter title shows above the chart.
  • Every shape. All of Mermaid's shapes work, including Mermaid 11's newer syntax, like A@{ shape: doc }. Each one becomes the closest Whimsical shape.
  • Formatted labels. Bold, italics and other formatting in labels is kept. Decision diamonds grow to fit their text, and long connector labels wrap.
  • All link styles. Open links (---) have no arrowhead, thick links (==>) are drawn as normal lines, and invisible links (~~~) only position their nodes. x and o ends work too.
  • Subgraphs. Subgraphs become grouped shapes. They can be nested, and each can have its own direction.
  • Colors. Style shapes and connectors with classDef, class, :::, style and linkStyle. Colors snap to the closest color in your board's palette.
  • Forgiving. A line Whimsical can't read only drops that line, not the whole chart. A diagram too big to draw pastes as text, with a message saying why.

Horizontal and vertical layoutsCopied!Link to this section

Whimsical honors all of Mermaid's flow directions:

  • TB top to bottom (TD “top down” also works)
  • LR left to right
  • RL right to left
  • BT bottom to top

Without a direction, the chart is laid out top to bottom. For a horizontal chart, put "flowchart LR" at the top of your code:

flowchart LR A([Client]) --> B[API Gateway] B --> C{Auth valid?} C -- No --> D[Return 401] C -- Yes --> E[Rate limiter] E --> F{Under limit?} F -- No --> G[Return 429] F -- Yes --> H[Route to service] H --> I[(Database)] I --> J[Return response]

If you're generating a flowchart with Whimsical AI, you can specify the layout direction in your prompt. For example, "Create a left-to-right flowchart of the user onboarding process."

ShapesCopied!Link to this section

  • [text] - Rectangle (so are (text), [[text]] and >text])
  • {text} - Diamond (decision)
  • ([text]) - Pill
  • ((text)) - Circle
  • {{text}} - Hexagon
  • [(text)] - Cylinder
  • [/text/] and [\text\] - Parallelogram
  • [/text\] and [\text/] - Trapezoid
  • A@{ shape: name } - Mermaid 11 shapes, matched to the closest Whimsical shape

ConnectorsCopied!Link to this section

  • --> - Arrow
  • --- - Line with no arrowhead
  • -->|Label| or -- Label --> - Labeled arrow
  • ==> - Thick arrow (drawn as a normal line)
  • <--> - Arrowheads at both ends
  • -.- - Dashed line; -.-> - Dashed arrow
  • x--x - Diamond ends; o--o - Circle ends
  • ~~~ - Invisible link (positions its nodes, no connector is drawn)
  • A & B --> C & D - Multi-node connections

StylingCopied!Link to this section

  • classDef className fill:#hex,stroke:#hex - Define a style class
  • :::className or class A,B className - Apply a class to nodes
  • style A fill:#hex - Style a single node
  • linkStyle 0,1,2 stroke:#hex - Color specific connectors (0-based index)
  • linkStyle 3 stroke:#hex,stroke-dasharray:5 5 - Dashed connector

Note: :::className only works with a matching classDef. Without one, it's ignored, and the rest of the diagram still pastes.

ER diagramsCopied!Link to this section

Paste an erDiagram and you get tables joined by crow's foot connectors:

  • Tables. Each entity becomes a table with its attributes, their keys (PK, FK, UK) and comments.
  • Relationships. Each relationship becomes a labeled connector, dashed when it isn't identifying.
  • Colors and groups. classDef, class and style color the table headings, and subgraphs become groups around their tables.

It also forgives common mistakes, like a relationship without a label or an attribute block that's never closed. Try it: copy this and paste it onto a board.

erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains PRODUCT ||--o{ LINE_ITEM : "appears in" CUSTOMER { int id PK string email UK "used to log in" } ORDER { int id PK int customer_id FK date placed_at }

Kanban boardsCopied!Link to this section

Paste a kanban and you get real Whimsical stacks and cards, not shapes:

  • Columns and cards. Each column becomes a stack with the column's name as its title, and each card becomes a card in that stack.
  • Card details. A card's ticket, assigned and priority go into its description. High priority cards are orange and Very High ones are red.
  • Both ways. Select stacks and choose Copy as… → Mermaid to get the kanban code back.

Try it: copy this and paste it onto a board.

kanban todo[To do] t1[Write release notes] t2[Update help article]@{ priority: 'High' } doing[In progress] t3[Record demo video]@{ assigned: 'Sam' } done[Done] t4[Ship kanban paste]@{ ticket: 'WEB-42', priority: 'Very High' }

Copy a diagram as MermaidCopied!Link to this section

You can copy flowcharts, ER diagrams, sequence diagrams, class diagrams, requirement diagrams and kanban stacks back out as Mermaid code for GitHub, Notion, GitLab or any other tool that renders Mermaid.

To copy a diagram as Mermaid code:

  1. Select the diagram you want to export.
  2. Right-click the selection and choose Copy as… → Mermaid from the context menu.
  3. Paste the Mermaid code wherever you need it.
  • Selected tables, the connectors between them and the groups around them copy as an erDiagram.
  • Flowcharts and ER diagrams keep their colors and direction. Colors are written as hex codes, so any Mermaid tool can read them.
  • Quotes and | in labels are kept, so the code pastes back exactly as it was.
  • Selected stacks copy as a kanban, with each stack as a column and its cards in order.
  • Event models copy back out as a flowchart.
  • Sequence diagram exports carry the participants, messages and arrow styles, but not colors.

For flowcharts, text colors come across too. Every styled shape carries an explicit text color in the exported code, so filled and outlined shapes (including subgraphs) keep readable labels in whatever tool you paste into. Shapes with no fill leave the text color out on purpose, so their labels follow the destination renderer's own light or dark theme.

Flowchart exports also set label wrapping on the whole diagram, so long labels that Whimsical reflows onto several lines reflow in other renderers instead of overflowing or getting clipped.

Nodes are output in topological order, so the code flows in the same direction as your diagram. This ensures compatibility with how tools like GitHub use text ordering to influence layout.

Sequence diagramsCopied!Link to this section

Paste a sequenceDiagram and you get everything Mermaid draws, not just participants and messages:

  • Participants and messages, with solid and dashed arrows and two-way arrows.
  • Notes beside or over participants.
  • Frames: loop, alt, opt, par, critical and break.
  • Grouping: rect backgrounds and box groups of participants.
  • Lifelines: activation bars, and lifelines that end where a participant is destroyed.
  • Numbering and titles: autonumber numbers your messages, and the diagram's title shows above it.

Cross, async and half arrowheads are drawn as plain arrows.

Use coding agents to build Mermaid diagrams with the MCPCopied!Link to this section

If you use a coding agent like Claude, Cursor, or Windsurf, you can connect it to Whimsical via the Whimsical MCP server. Then your coding agent can generate Mermaid diagrams and build them directly in your Whimsical workspace, without any copying and pasting.

It's a quick way to turn code, specs or prompts into any of the diagram types above. For example, you could ask your coding agent to:

  • "Generate a flowchart of this authentication flow and add it to my Whimsical board"
  • "Create a sequence diagram of the API calls in this file"
  • "Draw an ER diagram of the data model in this schema in Whimsical"
  • "Draw the architecture of this repo as an architecture diagram in Whimsical"
  • "Turn the open issues in this project into a kanban board in Whimsical"

Related articles