Beautiful Mermaid

Mermaid Rendering, made beautiful.

An open source library for rendering diagrams, designed for the age of AI: beautiful-mermaid. Ultra-fast, fully themeable, and outputs to both SVG and ASCII.
Built by the team at Craft — because diagrams deserve great design too.

Use in Craft Agents GitHub

Rendering 140 samples…

ASCII rendering based on Mermaid-ASCII
Early preview — actively evolving

Samples

Simple Flow

Basic linear flow with three nodes connected by solid arrows.

graph TD
  A[Start] --> B[Process] --> C[End]
Rendering…

Original Node Shapes

Rectangle, rounded, diamond, stadium, and circle.

graph LR
  A[Rectangle] --> B(Rounded)
  B --> C{Diamond}
  C --> D([Stadium])
  D --> E((Circle))
Rendering…

Batch 1 Shapes

Subroutine [[text]], double circle (((text))), and hexagon {{text}}.

graph LR
  A[[Subroutine]] --> B(((Double Circle)))
  B --> C{{Hexagon}}
Rendering…

Batch 2 Shapes

Cylinder [(text)], asymmetric >text], trapezoid [/text\], and inverse trapezoid [\text/].

graph LR
  A[(Database)] --> B>Flag Shape]
  B --> C[/Wider Bottom\]
  C --> D[\Wider Top/]
Rendering…

All 12 Flowchart Shapes

Every supported flowchart shape in a single diagram.

graph LR
  A[Rectangle] --> B(Rounded)
  B --> C{Diamond}
  C --> D([Stadium])
  D --> E((Circle))
  E --> F[[Subroutine]]
  F --> G(((Double Circle)))
  G --> H{{Hexagon}}
  H --> I[(Database)]
  I --> J>Flag]
  J --> K[/Trapezoid\]
  K --> L[\Inverse Trap/]
Rendering…

All Edge Styles

Solid, dotted, and thick arrows with labels.

graph TD
  A[Source] -->|solid| B[Target 1]
  A -.->|dotted| C[Target 2]
  A ==>|thick| D[Target 3]
Rendering…

No-Arrow Edges

Lines without arrowheads: solid ---, dotted -.-, thick ===.

graph TD
  A[Node 1] ---|related| B[Node 2]
  B -.- C[Node 3]
  C === D[Node 4]
Rendering…

Bidirectional Arrows

Arrows in both directions: <-->, <-.->, <==>.

graph LR
  A[Client] <-->|sync| B[Server]
  B <-.->|heartbeat| C[Monitor]
  C <==>|data| D[Storage]
Rendering…

Parallel Links (&)

Using & to create multiple edges from/to groups of nodes.

graph TD
  A[Input] & B[Config] --> C[Processor]
  C --> D[Output] & E[Log]
Rendering…

Chained Edges

A long chain of nodes demonstrating edge chaining syntax.

graph LR
  A[Step 1] --> B[Step 2] --> C[Step 3] --> D[Step 4] --> E[Step 5]
Rendering…

Direction: Left-Right (LR)

Horizontal layout flowing left to right.

graph LR
  A[Input] --> B[Transform] --> C[Output]
Rendering…

Direction: Bottom-Top (BT)

Vertical layout flowing from bottom to top.

graph BT
  A[Foundation] --> B[Layer 2] --> C[Top]
Rendering…

Subgraphs

Grouped nodes inside labeled subgraph containers.

graph TD
  subgraph Frontend
    A[React App] --> B[State Manager]
  end
  subgraph Backend
    C[API Server] --> D[Database]
  end
  B --> C
Rendering…

Nested Subgraphs

Subgraphs inside subgraphs for hierarchical grouping.

graph TD
  subgraph Cloud
    subgraph us-east [US East Region]
      A[Web Server] --> B[App Server]
    end
    subgraph us-west [US West Region]
      C[Web Server] --> D[App Server]
    end
  end
  E[Load Balancer] --> A
  E --> C
Rendering…

Subgraph Direction Override

Using direction LR inside a subgraph while the outer graph flows TD.

graph TD
  subgraph pipeline [Processing Pipeline]
    direction LR
    A[Input] --> B[Parse] --> C[Transform] --> D[Output]
  end
  E[Source] --> A
  D --> F[Sink]
Rendering…

::: Class Shorthand

Assigning classes with ::: syntax directly on node definitions.

graph TD
  A[Normal]:::default --> B[Highlighted]:::highlight --> C[Error]:::error
  classDef default fill:#f4f4f5,stroke:#a1a1aa
  classDef highlight fill:#fbbf24,stroke:#d97706
  classDef error fill:#ef4444,stroke:#dc2626
Rendering…

Inline Style Overrides

Using style statements to override node fill and stroke colors.

graph TD
  A[Default] --> B[Custom Colors] --> C[Another Custom]
  style B fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
  style C fill:#10b981,stroke:#059669
Rendering…

CI/CD Pipeline

A realistic CI/CD pipeline with decision points, feedback loops, and deployment stages.

graph TD
  subgraph ci [CI Pipeline]
    A[Push Code] --> B{Tests Pass?}
    B -->|Yes| C[Build Image]
    B -->|No| D[Fix & Retry]
    D -.-> A
  end
  C --> E([Deploy Staging])
  E --> F{QA Approved?}
  F -->|Yes| G((Production))
  F -->|No| D
Rendering…

System Architecture

A microservices architecture with multiple services and data stores.

graph LR
  subgraph clients [Client Layer]
    A([Web App]) --> B[API Gateway]
    C([Mobile App]) --> B
  end
  subgraph services [Service Layer]
    B --> D[Auth Service]
    B --> E[User Service]
    B --> F[Order Service]
  end
  subgraph data [Data Layer]
    D --> G[(Auth DB)]
    E --> H[(User DB)]
    F --> I[(Order DB)]
    F --> J([Message Queue])
  end
Rendering…

Decision Tree

A branching decision flowchart with multiple outcomes.

graph TD
  A{Is it raining?} -->|Yes| B{Have umbrella?}
  A -->|No| C([Go outside])
  B -->|Yes| D([Go with umbrella])
  B -->|No| E{Is it heavy?}
  E -->|Yes| F([Stay inside])
  E -->|No| G([Run for it])
Rendering…

Git Branching Workflow

A git flow showing feature branches, PRs, and release cycle.

graph LR
  A[main] --> B[develop]
  B --> C[feature/auth]
  B --> D[feature/ui]
  C --> E{PR Review}
  D --> E
  E -->|approved| B
  B --> F[release/1.0]
  F --> G{Tests?}
  G -->|pass| A
  G -->|fail| F
Rendering…

Basic State Diagram

A simple stateDiagram-v2 with start/end pseudostates and transitions.

stateDiagram-v2
  [*] --> Idle
  Idle --> Active : start
  Active --> Idle : cancel
  Active --> Done : complete
  Done --> [*]
Rendering…

State: Composite States

Nested composite states with inner transitions.

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing : submit
  state Processing {
    parse --> validate
    validate --> execute
  }
  Processing --> Complete : done
  Processing --> Error : fail
  Error --> Idle : retry
  Complete --> [*]
Rendering…

State: Connection Lifecycle

TCP-like connection state machine with multiple states.

stateDiagram-v2
  [*] --> Closed
  Closed --> Connecting : connect
  Connecting --> Connected : success
  Connecting --> Closed : timeout
  Connected --> Disconnecting : close
  Connected --> Reconnecting : error
  Reconnecting --> Connected : success
  Reconnecting --> Closed : max_retries
  Disconnecting --> Closed : done
  Closed --> [*]
Rendering…

Sequence: Basic Messages

Simple request/response between two participants.

sequenceDiagram
  Alice->>Bob: Hello Bob!
  Bob-->>Alice: Hi Alice!
Rendering…

Sequence: Participant Aliases

Using participant ... as ... for compact diagram IDs with readable labels.

sequenceDiagram
  participant A as Alice
  participant B as Bob
  participant C as Charlie
  A->>B: Hello
  B->>C: Forward
  C-->>A: Reply
Rendering…

Sequence: Actor Stick Figures

Using actor instead of participant renders stick figures instead of boxes.

sequenceDiagram
  actor U as User
  participant S as System
  participant DB as Database
  U->>S: Click button
  S->>DB: Query
  DB-->>S: Results
  S-->>U: Display
Rendering…

Sequence: Arrow Types

All arrow types: solid ->> and dashed -->> with filled arrowheads, open arrows -) .

sequenceDiagram
  A->>B: Solid arrow (sync)
  B-->>A: Dashed arrow (return)
  A-)B: Open arrow (async)
  B--)A: Open dashed arrow
Rendering…

Sequence: Activation Boxes

Using + and - to show when participants are active.

sequenceDiagram
  participant C as Client
  participant S as Server
  C->>+S: Request
  S->>+S: Process
  S->>-S: Done
  S-->>-C: Response
Rendering…

Sequence: Self-Messages

A participant sending a message to itself (displayed as a loop arrow).

sequenceDiagram
  participant S as Server
  S->>S: Internal process
  S->>S: Validate
  S-->>S: Log
Rendering…

Sequence: Loop Block

A loop construct wrapping repeated message exchanges.

sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: Connect
  loop Every 30s
    C->>S: Heartbeat
    S-->>C: Ack
  end
  C->>S: Disconnect
Rendering…

Sequence: Alt/Else Block

Conditional branching with alt (if) and else blocks.

sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: Login
  alt Valid credentials
    S-->>C: 200 OK
  else Invalid
    S-->>C: 401 Unauthorized
  else Account locked
    S-->>C: 403 Forbidden
  end
Rendering…

Sequence: Opt Block

Optional block — executes only if condition is met.

sequenceDiagram
  participant A as App
  participant C as Cache
  participant DB as Database
  A->>C: Get data
  C-->>A: Cache miss
  opt Cache miss
    A->>DB: Query
    DB-->>A: Results
    A->>C: Store in cache
  end
Rendering…

Sequence: Par Block

Parallel execution with par/and constructs.

sequenceDiagram
  participant C as Client
  participant A as AuthService
  participant U as UserService
  participant O as OrderService
  C->>A: Authenticate
  par Fetch user data
    A->>U: Get profile
  and Fetch orders
    A->>O: Get orders
  end
  A-->>C: Combined response
Rendering…

Sequence: Critical Block

Critical section that must complete atomically.

sequenceDiagram
  participant A as App
  participant DB as Database
  A->>DB: BEGIN
  critical Transaction
    A->>DB: UPDATE accounts
    A->>DB: INSERT log
  end
  A->>DB: COMMIT
Rendering…

Sequence: Notes (Right/Left/Over)

Notes positioned to the right, left, or over participants.

sequenceDiagram
  participant A as Alice
  participant B as Bob
  Note left of A: Alice prepares
  A->>B: Hello
  Note right of B: Bob thinks
  B-->>A: Reply
  Note over A,B: Conversation complete
Rendering…

Sequence: OAuth 2.0 Flow

Full OAuth 2.0 authorization code flow with token exchange.

sequenceDiagram
  actor U as User
  participant App as Client App
  participant Auth as Auth Server
  participant API as Resource API
  U->>App: Click Login
  App->>Auth: Authorization request
  Auth->>U: Login page
  U->>Auth: Credentials
  Auth-->>App: Authorization code
  App->>Auth: Exchange code for token
  Auth-->>App: Access token
  App->>API: Request + token
  API-->>App: Protected resource
  App-->>U: Display data
Rendering…

Sequence: Database Transaction

Multi-step database transaction with rollback handling.

sequenceDiagram
  participant C as Client
  participant S as Server
  participant DB as Database
  C->>S: POST /transfer
  S->>DB: BEGIN
  S->>DB: Debit account A
  alt Success
    S->>DB: Credit account B
    S->>DB: INSERT audit_log
    S->>DB: COMMIT
    S-->>C: 200 OK
  else Insufficient funds
    S->>DB: ROLLBACK
    S-->>C: 400 Bad Request
  end
Rendering…

Sequence: Microservice Orchestration

Complex multi-service flow with parallel calls and error handling.

sequenceDiagram
  participant G as Gateway
  participant A as Auth
  participant U as Users
  participant O as Orders
  participant N as Notify
  G->>A: Validate token
  A-->>G: Valid
  par Fetch data
    G->>U: Get user
    U-->>G: User data
  and
    G->>O: Get orders
    O-->>G: Order list
  end
  G->>N: Send notification
  N-->>G: Queued
  Note over G: Aggregate response
Rendering…

Class: Basic Class

A single class with attributes and methods, rendered as a 3-compartment box.

classDiagram
  class Animal {
    +String name
    +int age
    +eat() void
    +sleep() void
  }
Rendering…

Class: Visibility Markers

All four visibility levels: + (public), - (private), # (protected), ~ (package).

classDiagram
  class User {
    +String name
    -String password
    #int internalId
    ~String packageField
    +login() bool
    -hashPassword() String
    #validate() void
    ~notify() void
  }
Rendering…

Class: Interface Annotation

Using <> annotation above the class name.

classDiagram
  class Serializable {
    <<interface>>
    +serialize() String
    +deserialize(data) void
  }
Rendering…

Class: Abstract Annotation

Using <> annotation for abstract classes.

classDiagram
  class Shape {
    <<abstract>>
    +String color
    +area() double
    +draw() void
  }
Rendering…

Class: Enum Annotation

Using <> annotation for enum types.

classDiagram
  class Status {
    <<enumeration>>
    ACTIVE
    INACTIVE
    PENDING
    DELETED
  }
Rendering…

Class: Inheritance (<|--)

Inheritance relationship rendered with a hollow triangle marker.

classDiagram
  class Animal {
    +String name
    +eat() void
  }
  class Dog {
    +String breed
    +bark() void
  }
  class Cat {
    +bool isIndoor
    +meow() void
  }
  Animal <|-- Dog
  Animal <|-- Cat
Rendering…

Class: Composition (*--)

Composition — "owns" relationship with filled diamond marker.

classDiagram
  class Car {
    +String model
    +start() void
  }
  class Engine {
    +int horsepower
    +rev() void
  }
  Car *-- Engine
Rendering…

Class: Aggregation (o--)

Aggregation — "has" relationship with hollow diamond marker.

classDiagram
  class University {
    +String name
  }
  class Department {
    +String faculty
  }
  University o-- Department
Rendering…

Class: Association (-->)

Basic association — simple directed arrow.

classDiagram
  class Customer {
    +String name
  }
  class Order {
    +int orderId
  }
  Customer --> Order
Rendering…

Class: Dependency (..>)

Dependency — dashed line with open arrow.

classDiagram
  class Service {
    +process() void
  }
  class Repository {
    +find() Object
  }
  Service ..> Repository
Rendering…

Class: Realization (..|>)

Realization — dashed line with hollow triangle (implements interface).

classDiagram
  class Flyable {
    <<interface>>
    +fly() void
  }
  class Bird {
    +fly() void
    +sing() void
  }
  Bird ..|> Flyable
Rendering…

Class: All 6 Relationship Types

Every relationship type in a single diagram for comparison.

classDiagram
  A <|-- B : inheritance
  C *-- D : composition
  E o-- F : aggregation
  G --> H : association
  I ..> J : dependency
  K ..|> L : realization
Rendering…

Class: Relationship Labels

Labeled relationships between classes with descriptive text.

classDiagram
  class Teacher {
    +String name
  }
  class Student {
    +String name
  }
  class Course {
    +String title
  }
  Teacher --> Course : teaches
  Student --> Course : enrolled in
Rendering…

Class: Design Pattern — Observer

The Observer (publish-subscribe) design pattern with interface + concrete implementations.

classDiagram
  class Subject {
    <<interface>>
    +attach(Observer) void
    +detach(Observer) void
    +notify() void
  }
  class Observer {
    <<interface>>
    +update() void
  }
  class EventEmitter {
    -List~Observer~ observers
    +attach(Observer) void
    +detach(Observer) void
    +notify() void
  }
  class Logger {
    +update() void
  }
  class Alerter {
    +update() void
  }
  Subject <|.. EventEmitter
  Observer <|.. Logger
  Observer <|.. Alerter
  EventEmitter --> Observer
Rendering…

Class: MVC Architecture

Model-View-Controller pattern showing relationships between layers.

classDiagram
  class Model {
    -data Map
    +getData() Map
    +setData(key, val) void
    +notify() void
  }
  class View {
    -model Model
    +render() void
    +update() void
  }
  class Controller {
    -model Model
    -view View
    +handleInput(event) void
    +updateModel(data) void
  }
  Controller --> Model : updates
  Controller --> View : refreshes
  View --> Model : reads
  Model ..> View : notifies
Rendering…

Class: Full Hierarchy

A complete class hierarchy with abstract base, interfaces, and concrete classes.

classDiagram
  class Animal {
    <<abstract>>
    +String name
    +int age
    +eat() void
    +sleep() void
  }
  class Mammal {
    +bool warmBlooded
    +nurse() void
  }
  class Bird {
    +bool canFly
    +layEggs() void
  }
  class Dog {
    +String breed
    +bark() void
  }
  class Cat {
    +bool isIndoor
    +purr() void
  }
  class Parrot {
    +String vocabulary
    +speak() void
  }
  Animal <|-- Mammal
  Animal <|-- Bird
  Mammal <|-- Dog
  Mammal <|-- Cat
  Bird <|-- Parrot
Rendering…

ER: Basic Relationship

A simple one-to-many relationship between two entities.

erDiagram
  CUSTOMER ||--o{ ORDER : places
Rendering…

ER: Entity with Attributes

An entity with typed attributes and PK/FK/UK key badges.

erDiagram
  CUSTOMER {
    int id PK
    string name
    string email UK
    date created_at
  }
Rendering…

ER: Attribute Keys (PK, FK, UK)

All three key constraint types rendered as badges.

erDiagram
  ORDER {
    int id PK
    int customer_id FK
    string invoice_number UK
    decimal total
    date order_date
    string status
  }
Rendering…

ER: Exactly One to Exactly One (||--||)

One-to-one mandatory relationship.

erDiagram
  PERSON ||--|| PASSPORT : has
Rendering…

ER: Exactly One to Zero-or-Many (||--o{)

Classic one-to-many optional relationship (crow's foot).

erDiagram
  CUSTOMER ||--o{ ORDER : places
Rendering…

ER: Zero-or-One to One-or-Many (|o--|{)

Optional on one side, at-least-one on the other.

erDiagram
  SUPERVISOR |o--|{ EMPLOYEE : manages
Rendering…

ER: One-or-More to Zero-or-Many (}|--o{)

At-least-one to zero-or-many relationship.

erDiagram
  TEACHER }|--o{ COURSE : teaches
Rendering…

ER: All Cardinality Types

Every cardinality combination in one diagram.

erDiagram
  A ||--|| B : one-to-one
  C ||--o{ D : one-to-many
  E |o--|{ F : opt-to-many
  G }|--o{ H : many-to-many
Rendering…

ER: Identifying (Solid) Relationship

Solid line indicating an identifying relationship (child depends on parent for identity).

erDiagram
  ORDER ||--|{ LINE_ITEM : contains
Rendering…

ER: Non-Identifying (Dashed) Relationship

Dashed line indicating a non-identifying relationship.

erDiagram
  USER ||..o{ LOG_ENTRY : generates
  USER ||..o{ SESSION : opens
Rendering…

ER: Mixed Identifying & Non-Identifying

Both solid and dashed lines in the same diagram.

erDiagram
  ORDER ||--|{ LINE_ITEM : contains
  ORDER ||..o{ SHIPMENT : ships-via
  PRODUCT ||--o{ LINE_ITEM : includes
  PRODUCT ||..o{ REVIEW : receives
Rendering…

ER: E-Commerce Schema

Full e-commerce database schema with customers, orders, products, and line items.

erDiagram
  CUSTOMER {
    int id PK
    string name
    string email UK
  }
  ORDER {
    int id PK
    date created
    int customer_id FK
  }
  PRODUCT {
    int id PK
    string name
    float price
  }
  LINE_ITEM {
    int id PK
    int order_id FK
    int product_id FK
    int quantity
  }
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  PRODUCT ||--o{ LINE_ITEM : includes
Rendering…

ER: Blog Platform Schema

Blog system with users, posts, comments, and tags.

erDiagram
  USER {
    int id PK
    string username UK
    string email UK
    date joined
  }
  POST {
    int id PK
    string title
    text content
    int author_id FK
    date published
  }
  COMMENT {
    int id PK
    text body
    int post_id FK
    int user_id FK
    date created
  }
  TAG {
    int id PK
    string name UK
  }
  USER ||--o{ POST : writes
  USER ||--o{ COMMENT : authors
  POST ||--o{ COMMENT : has
  POST }|--o{ TAG : tagged-with
Rendering…

ER: School Management Schema

School system with students, teachers, courses, and enrollments.

erDiagram
  STUDENT {
    int id PK
    string name
    date dob
    string grade
  }
  TEACHER {
    int id PK
    string name
    string department
  }
  COURSE {
    int id PK
    string title
    int teacher_id FK
    int credits
  }
  ENROLLMENT {
    int id PK
    int student_id FK
    int course_id FK
    string semester
    float grade
  }
  TEACHER ||--o{ COURSE : teaches
  STUDENT ||--o{ ENROLLMENT : enrolled
  COURSE ||--o{ ENROLLMENT : has
Rendering…