Skip to content
Get packs

Guide · Open source

How to use beautiful-mermaid: render Mermaid to SVG or ASCII

Updated · written with AI from the project's own documentation and checked against our catalogue data

beautiful-mermaid is a TypeScript library that turns Mermaid diagram text into SVG images or ASCII/Unicode art. It is aimed at developers who want to show diagrams inside web apps, chat interfaces or plain terminals. After this guide you will be able to install it, render a diagram to SVG or ASCII, use it in React, and apply a built-in or custom theme.

beautiful-mermaidlukilabs/beautiful-mermaid · ★ 11.3k · MIT

Quick start

  1. 1Install the package. Run npm install beautiful-mermaid, or use bun add or pnpm add instead.
  2. 2Choose an output type. Use renderMermaidSVG for web UIs or renderMermaidASCII for terminals.
  3. 3Pass in Mermaid text. Give the render function a Mermaid diagram string such as a graph TD flowchart.
  4. 4Use the returned string. Insert the SVG string into your page, or print the ASCII text to the terminal.
  5. 5Pick colors. Pass bg and fg, add optional enrichments, or use a built-in theme from THEMES.

Install beautiful-mermaid with npm, bun or pnpm

beautiful-mermaid is installed as a package with your usual package manager. The README lists npm, bun and pnpm. You need Node.js, Bun or pnpm available on your machine.

  • npm: install beautiful-mermaid
  • bun: add beautiful-mermaid
  • pnpm: add beautiful-mermaid
npm install beautiful-mermaid

Render a Mermaid diagram to SVG

Import renderMermaidSVG and pass it your Mermaid diagram text. It returns an SVG string. Rendering is fully synchronous, so there is no await or promise to handle. The README says the ELK.js layout engine runs synchronously via a FakeWorker bypass.

If you prefer a promise, renderMermaidSVGAsync() gives the same output and returns a Promise<string>.

import { renderMermaidSVG } from 'beautiful-mermaid'; const svg = renderMermaidSVG(`graph TD; A[Start] --> B{Decision}; B -->|Yes| C[Action]; B -->|No| D[End]`)

Render a diagram as ASCII or Unicode for the terminal

For CLI tools or plain terminals, use renderMermaidASCII. It returns text art built from box characters and arrows. The README example renders a three-node left-to-right flowchart.

The ASCII engine is based on mermaid-ascii by Alexander Grooff. beautiful-mermaid ports it from Go to TypeScript and extends it.

import { renderMermaidASCII } from 'beautiful-mermaid'; const ascii = renderMermaidASCII(`graph LR; A --> B --> C`)

Use beautiful-mermaid in a React component

Because rendering is synchronous, you can call it inside React.useMemo() so the diagram is computed during render rather than in an effect. The README pattern wraps the call in try/catch and shows the error message if rendering fails.

Pass CSS variables such as var(--background) for bg and fg, with transparent set to true. The SVG then inherits your app's theme, and switches apply without re-rendering. The diagram recomputes only when the code string changes.

  • No flash: the SVG is computed during render, not in useEffect
  • CSS variables: colors follow your app's stylesheet
  • Memoized: re-renders only when code changes
const { svg, error } = React.useMemo(() => { try { return { svg: renderMermaidSVG(code, { bg: 'var(--background)', fg: 'var(--foreground)', transparent: true }), error: null } } catch (err) { return { svg: null, error: err instanceof Error ? err : new Error(String(err)) } } }, [code])

Theme diagrams with two colors or a built-in theme

Every diagram needs two colors: bg (background) and fg (foreground). The library derives the rest of the diagram colors from these with color-mix(). This is called Mono Mode.

For more control, add optional enrichment colors such as line, accent, muted, surface and border. Any you leave out fall back to the derived value.

The package ships 15 built-in themes, exposed as THEMES. Examples include tokyo-night, dracula, nord, catppuccin-mocha and github-dark. You can also write your own theme with only bg and fg.

  • Two-color base: bg and fg
  • Optional enrichments: line, accent, muted, surface, border
  • Built-in: THEMES['tokyo-night'] and 14 others
  • Live switching: all colors are CSS custom properties on the svg element
import { renderMermaidSVG, THEMES } from 'beautiful-mermaid'; const svg = renderMermaidSVG(diagram, THEMES['tokyo-night'])

Use a VS Code or Shiki theme for diagram colors

The README says beautiful-mermaid is compatible with Shiki, so you can use any VS Code theme. You load themes with Shiki's getSingletonHighlighter, then convert one with fromShikiTheme(). That function maps editor colors such as editor.background and editor.foreground to diagram roles.

import { getSingletonHighlighter } from 'shiki'; import { renderMermaidSVG, fromShikiTheme } from 'beautiful-mermaid'; const highlighter = await getSingletonHighlighter({ themes: ['vitesse-dark'] }); const svg = renderMermaidSVG(diagram, fromShikiTheme(highlighter.getTheme('vitesse-dark')))

What people use it for

  • Showing flowcharts or sequence diagrams inside a React chat or AI assistant interface
  • Printing a data flow or state machine as text in a command-line tool
  • Matching diagram colors to an app that already uses Tokyo Night or Dracula
  • Rendering ER or class diagrams from text in a documentation-style web page

Frequently asked questions

Is beautiful-mermaid free to use?

beautiful-mermaid is released under the MIT licence, as shown in the README and repository badge. The MIT licence permits use with few restrictions, but check the LICENSE file in the repository for the full terms.

How do I install beautiful-mermaid?

Run npm install beautiful-mermaid, bun add beautiful-mermaid, or pnpm add beautiful-mermaid. The package is written in TypeScript and is installed from npm through one of these three package managers.

What do I need to run beautiful-mermaid?

The README lists Node.js, Bun or pnpm as prerequisites, alongside the package manager install commands. The examples use TypeScript and React, so a JavaScript or TypeScript project is the expected setup.

What diagram types does beautiful-mermaid support?

The README lists six types: flowcharts, state, sequence, class, ER, and XY charts (bar, line and combined). If you need a Mermaid diagram type outside this list, check it before you adopt the library.

How is beautiful-mermaid different from mermaid?

The README says the default Mermaid renderer has weak default aesthetics, complex theming that relies on CSS classes, no ASCII output, and heavy dependencies. beautiful-mermaid addresses these with two-color theming, ASCII output and zero DOM dependencies.

What is mermaid-ascii and how does it relate?

mermaid-ascii is a separate project by Alexander Grooff. beautiful-mermaid's ASCII renderer is ported from it from Go to TypeScript and extended, and the README credits that project as its foundation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use beautiful-mermaid if you are a developer who needs Mermaid diagrams rendered synchronously in JavaScript or TypeScript code, in web UIs, terminals or AI assistant interfaces, with theme control. Pick the standard mermaid package or another tool if you need diagram types outside the six listed, or you work in a non-JavaScript stack.

Install options & downloads