Repolode
Submit
lukilabs

lukilabs/beautiful-mermaid

A TypeScript library that renders Mermaid diagrams to themeable SVG or ASCII/Unicode text, with no DOM dependencies.

View on GitHub
Stars
11,200
Forks
411
Open issues
93
Last commit
6 months ago

What is it?

beautiful-mermaid turns Mermaid diagram source into SVG strings or plain-text ASCII/Unicode art. It supports flowcharts, state, sequence, class, and ER diagrams, plus XY charts with bar, line, and combined series.

Rendering is synchronous, so SVG output can be computed directly during a React render with useMemo. Themes are built from two colors, background and foreground, with optional accent and muted colors. Colors are exposed as CSS custom properties, so theme changes can be applied without re-rendering. The library also includes 15 built-in themes and can map any Shiki (VS Code) theme to diagram colors.

The ASCII renderer is a TypeScript port of the Go project mermaid-ascii, extended with sequence, class, and ER support. It can output Unicode box-drawing characters or pure ASCII, with optional ANSI or HTML coloring for terminal use.

Key features

  • 01Renders flowcharts, state, sequence, class, ER, and XY charts
  • 02Outputs SVG for web UIs or ASCII/Unicode text for terminals
  • 03Synchronous API that works inside React render with useMemo
  • 04Themes derived from two colors, with 15 built-in themes
  • 05Accepts any Shiki/VS Code theme through fromShikiTheme
  • 06Live theme switching through CSS custom properties

Use cases

  • Showing generated flowcharts or diagrams inside an AI chat or agent interface
  • Displaying Mermaid diagrams in a React app without async loading
  • Printing architecture or state diagrams in CLI tools and terminal output
  • Matching diagram colors to an existing editor or app theme

Quick start

  1. 1

    Install the package with npm

    npm install beautiful-mermaid
  2. 2

    Render a flowchart to SVG in code

Things to know

  • Rendering is synchronous, but the ELK.js layout runs via a FakeWorker bypass, so very large diagrams may be slower.
  • The README lists six diagram types only; other Mermaid diagram types are not covered.

Topics

#mermaid#diagram#svg#ascii#typescript#theming#charts

FAQ

What is beautiful-mermaid?
A TypeScript library that renders Mermaid diagrams to themeable SVG or ASCII/Unicode text, with no DOM dependencies. beautiful-mermaid turns Mermaid diagram source into SVG strings or plain-text ASCII/Unicode art. It supports flowcharts, state, sequence, class, and ER diagrams, plus XY charts with bar, line, and combined series.
Is beautiful-mermaid free to use? What license does it have?
beautiful-mermaid is open source under the MIT license. Check the license terms before using it in commercial products.
Is beautiful-mermaid still maintained?
Updated within 6 months. The last commit to beautiful-mermaid was on May 6, 2026.
What can I use beautiful-mermaid for?
Showing generated flowcharts or diagrams inside an AI chat or agent interface Displaying Mermaid diagrams in a React app without async loading Printing architecture or state diagrams in CLI tools and terminal output Matching diagram colors to an existing editor or app theme
How do I install beautiful-mermaid?
Install the package with npm: npm install beautiful-mermaid Render a flowchart to SVG in code
Where can I get beautiful-mermaid?
The source code and installation instructions are on GitHub: https://github.com/lukilabs/beautiful-mermaid

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects