beautiful-mermaid
Renders Mermaid text diagrams as SVG or terminal ASCII, with themes, no DOM needed.
- Stars
- 11.3k
- Forks
- 414
- Licence
- MIT
- Language
- TypeScript
- Last update
- 6 months ago
- Type
- Library
What it is
beautiful-mermaid is a TypeScript library that turns Mermaid diagram text (flowcharts, sequence, class, state, ER, and XY charts) into SVG images or ASCII/Unicode art. It is meant for showing diagrams inside web apps, chat interfaces, or plain terminals, and it has a theming system for matching diagram colors to an app's look.
- Render a flowchart from Mermaid text into an SVG string inside a web page
- Show a sequence or state diagram in a terminal as ASCII/Unicode art
- Switch diagram colors live by updating CSS custom properties without re-rendering
- Apply a built-in theme or a VS Code theme via Shiki to diagrams
Great for
- Web developers who want Mermaid diagrams rendered synchronously inside React or other UI code
- Developers building CLI or terminal tools that need text-based diagram output
- Teams who want Mermaid diagrams to match an existing color theme such as Tokyo Night or Dracula
- Developers building AI coding assistant interfaces that display diagrams
Not ideal for
- Users who only need diagrams in a finished document and do not write code; the README describes a library with no standalone app
- Projects needing every Mermaid diagram type; the README lists 6 supported types, so check whether yours is included
- Non-JavaScript stacks, since the README shows only TypeScript and npm/bun/pnpm installs
How to get it
- 1
Install with a package manager
You'll need: Node.js or Bun or pnpm
Install with npm
npm install beautiful-mermaidInstall with bun
bun add beautiful-mermaidInstall with pnpm
pnpm add beautiful-mermaid - 2
Run it
- Install the package with npm, bun, or pnpm
- Import renderMermaidSVG from 'beautiful-mermaid' in your code
- Pass a Mermaid diagram string such as 'graph TD; A --> B' to renderMermaidSVG to get an SVG string
- Or import renderMermaidASCII to get text output for a terminal
- 3
Get the most out of it
- Use bg and fg with CSS variables like var(--background) so diagrams follow your app's theme automatically
- Add optional enrichment colors (line, accent, muted, surface, border) for richer themes
- Load any VS Code theme through Shiki with fromShikiTheme() to reuse editor colors
- Use renderMermaidSVGAsync() if you need an async variant that returns a Promise
Downloads
Strengths
- Synchronous rendering works with React useMemo() without a loading flash, according to the README
- Supports both SVG output for UIs and ASCII/Unicode output for terminals
- Themeable with just two colors (background and foreground), with 15 built-in themes
Trade-offs
- The README is truncated and does not show full API options or every supported syntax detail
- The ASCII engine is a port of a Go project, so some diagram features may behave differently from the official Mermaid renderer (not stated explicitly; treat with caution)
- No description or homepage metadata, and the latest release has no binaries, so it is used purely as a package
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| beautiful-mermaid (this) | 11.3k | Library | intermediate | 6 months ago | Web developers who want Mermaid diagrams rendered synchronously inside React or other UI code |
| mermaid | 91k | Dev tool | beginner | 4 days ago | Developers who want diagrams stored as text alongside their code and docs |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.