@vercel/beautiful-mermaid

beautiful-mermaid

Render Mermaid diagrams as beautiful SVGs or ASCII art

Ultra-fast, fully themeable, animated, zero DOM dependencies. Built for the AI era.

Live Demo & Samples

→ Use it live in Craft Agents

Features

• 5 diagram types — Flowcharts, State, Sequence, Class, and ER diagrams
• Dual output — SVG for rich UIs, ASCII/Unicode for terminals
• 17 built-in themes — Including Vercel dark/light, and dead simple to add your own
• Rank-by-rank animation — Nodes fade in, edges draw in with traveling arrows, CSS + SMIL
• Full Shiki compatibility — Use any VS Code theme directly
• Live theme switching — CSS custom properties, no re-render needed
• Mono mode — Beautiful diagrams from just 2 colors
• Zero DOM dependencies — Pure TypeScript, works everywhere
• Ultra-fast — Renders 100+ diagrams in under 500ms

Installation

npm install beautiful-mermaid

Quick Start

SVG Output

import { renderMermaid } from 'beautiful-mermaid'

const svg = await renderMermaid(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)

With Animation

const svg = await renderMermaid(diagram, {
  animate: true,  // rank-by-rank animation with sane defaults
})

// Or customize:
const svg = await renderMermaid(diagram, {
  animate: {
    duration: 650,
    stagger: 0,
    nodeOverlap: 0.35,
    nodeAnimation: 'fade-up',
  },
})

ASCII Output

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)

┌───┐     ┌───┐     ┌───┐
│   │     │   │     │   │
│ A │────►│ B │────►│ C │
│   │     │   │     │   │
└───┘     └───┘     └───┘

Browser (Script Tag)

<script src="https://unpkg.com/beautiful-mermaid/dist/beautiful-mermaid.browser.global.js"></script>
<script>
  const { renderMermaid, THEMES } = beautifulMermaid;
  renderMermaid('graph TD; A-->B', { ...THEMES['vercel-dark'], animate: true })
    .then(svg => { ... });
</script>

Theming

The Two-Color Foundation

Every diagram needs just two colors: background (bg) and foreground (fg):

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
})

Everything else is derived via color-mix().

Enriched Mode

Override specific derived colors:

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
  line: '#3d59a1',    // Edge/connector color
  accent: '#7aa2f7',  // Arrow heads, highlights
  muted: '#565f89',   // Secondary text, labels
  surface: '#292e42', // Node fill tint
  border: '#3d59a1',  // Node stroke
})

Built-in Themes

17 themes ship out of the box:

import { renderMermaid, THEMES } from 'beautiful-mermaid'

const svg = await renderMermaid(diagram, THEMES['vercel-dark'])

Theme	Type	Background
vercel-dark	Dark	#0A0A0A
vercel-light	Light	#FFFFFF
tokyo-night	Dark	#1a1b26
tokyo-night-storm	Dark	#24283b
tokyo-night-light	Light	#d5d6db
catppuccin-mocha	Dark	#1e1e2e
catppuccin-latte	Light	#eff1f5
nord	Dark	#2e3440
nord-light	Light	#eceff4
dracula	Dark	#282a36
github-light	Light	#ffffff
github-dark	Dark	#0d1117
solarized-light	Light	#fdf6e3
solarized-dark	Dark	#002b36
one-dark	Dark	#282c34
zinc-dark	Dark	#18181B

Default theme (when no colors provided) is Vercel dark (#0A0A0A / #EDEDED).

Shiki Compatibility

Use any VS Code theme via Shiki:

import { getSingletonHighlighter } from 'shiki'
import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid'

const hl = await getSingletonHighlighter({ themes: ['vitesse-dark'] })
const colors = fromShikiTheme(hl.getTheme('vitesse-dark'))
const svg = await renderMermaid(diagram, colors)

Animation

Pass animate: true for rank-by-rank animation with sane defaults, or customize with AnimationOptions.

How It Works

• Nodes fade in rank-by-rank (top → bottom)
• Edges draw in via stroke-dashoffset with pathLength="1"
• Arrow tips travel along the path via SMIL <animateMotion>, synced with edge easing
• Subgroups fade in after their contents are mostly visible
• Cascade: source node → edge draws → target node appears (with configurable overlap)

All CSS-based (works in standalone SVG files, no JS runtime needed). SMIL used only for arrow travel.

AnimationOptions

interface AnimationOptions {
  duration?: number        // Each element's animation duration (ms). Default: 650
  stagger?: number         // Delay between consecutive elements (ms). Default: 0
  nodeOverlap?: number     // How early node appears before incoming edge finishes
                           // (0 = wait, 0.5 = halfway, 1 = with edge). Default: 0.35
  groupDelay?: number      // Extra offset for group container (ms). Default: 110
  nodeEasing?: string      // CSS easing for nodes/groups. Default: 'ease'
  edgeEasing?: string      // CSS easing for edge draw-in + arrow travel. Default: 'ease-in-out'
  nodeAnimation?: string   // 'fade' | 'fade-up' | 'scale' | 'none'. Default: 'fade'
  edgeAnimation?: string   // 'draw' | 'fade' | 'none'. Default: 'draw'
  reducedMotion?: boolean  // Respect prefers-reduced-motion. Default: true
}

Easing Design

Element	Easing	Rationale
Nodes/groups	nodeEasing	Elements "appear" — deceleration curve
Edge lines	edgeEasing	Lines "flow" — acceleration/deceleration
Arrow tips	auto-derived from edgeEasing	SMIL keySplines converted from CSS cubic-bezier, guaranteed sync
Edge labels	nodeEasing	Labels are content, not motion

Accessibility

When reducedMotion: true (default), a @media (prefers-reduced-motion: reduce) block disables all animations, showing the diagram instantly.

Layout & Styling Options

RenderOptions

Option	Type	Default	Description
bg	string	#0A0A0A	Background color
fg	string	#EDEDED	Foreground color
line	string?	—	Edge/connector color
accent	string?	—	Arrow heads, highlights
muted	string?	—	Secondary text, labels
surface	string?	—	Node fill tint
border	string?	—	Node stroke color
font	string	Geist	Font family
fontSize	number	19.2	Node label font size (px)
fontWeight	number	400	Node label font weight
letterSpacing	number	-0.384	Node label letter spacing (px)
edgeFontSize	number	10	Edge label font size (px)
nodePaddingX	number	24	Horizontal padding inside nodes (px)
nodePaddingY	number	24	Vertical padding inside nodes (px)
cornerRadius	number	6	Node corner radius (px)
lineWidth	number	1.5	Edge stroke width (px)
edgeBendRadius	number	8	Rounded corners on edge bends (px)
padding	number	80	Canvas padding (px)
nodeSpacing	number	40	Horizontal spacing between nodes (px)
layerSpacing	number	50	Vertical spacing between layers (px)
transparent	boolean	false	Transparent background
animate	boolean | AnimationOptions	false	Enable animation

Subgraph Options

Option	Type	Default	Description
groupFont	string	Geist Mono	Subgraph header font family
groupFontSize	number	16	Subgraph header font size (px)
groupFontWeight	number	600	Subgraph header font weight
groupTextTransform	string	uppercase	Subgraph header text transform
groupCornerRadius	number	3	Subgraph corner radius (px)
groupBorderColor	string	#454545	Subgraph border color
groupPaddingX	number	32	Subgraph horizontal padding (px)
groupPaddingY	number	32	Subgraph vertical padding (px)

Subgraph backgrounds use a diagonal hatching pattern.

Supported Diagrams

Flowcharts

graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Process]
  B -->|No| D[End]

All directions: TD, LR, BT, RL. Subgraphs supported.

State Diagrams

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing: start
  Processing --> Complete: done
  Complete --> [*]

Sequence Diagrams

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

Class Diagrams

classDiagram
  Animal <|-- Duck
  Animal: +int age
  Duck: +swim()

ER Diagrams

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains

ASCII Output

import { renderMermaidAscii } from 'beautiful-mermaid'

const unicode = renderMermaidAscii(`graph LR; A --> B`)
const ascii = renderMermaidAscii(`graph LR; A --> B`, { useAscii: true })

Option	Type	Default	Description
useAscii	boolean	false	ASCII instead of Unicode
paddingX	number	5	Horizontal node spacing
paddingY	number	5	Vertical node spacing
boxBorderPadding	number	1	Inner box padding

Attribution

ASCII rendering based on mermaid-ascii by Alexander Grooff (ported from Go, extended with sequence/class/ER support).

License

MIT — see LICENSE for details.

Built with care by the team at Craft