Beautiful-mermaid is a TypeScript library that renders Mermaid diagrams as beautiful SVGs or ASCII art with full theming support.
The tool addresses limitations in Mermaid's default renderer: diagrams often lack visual polish, theming requires wrestling with CSS classes, terminal output is unavailable, and the renderer carries heavy dependencies. Beautiful-mermaid solves this by providing a lightweight, fully synchronous rendering engine that outputs either SVG for rich interfaces or ASCII for terminal environments. The rendering happens synchronously without async operations, enabling integration with React's useMemo for zero-flash diagram updates. The theming system centers on a two-color foundation—background and foreground—from which the entire diagram is automatically derived using CSS color-mix functions, allowing live theme switching through CSS custom properties without re-rendering.
The tool supports six diagram types: flowcharts, state machines, sequence diagrams, class diagrams, entity-relationship diagrams, and XY charts. It includes fifteen built-in themes and full compatibility with any VS Code theme through Shiki. The project suits developers building AI-assisted programming tools, terminal-based interfaces, or applications requiring diagram visualization without heavy dependencies. It works everywhere TypeScript runs, with no DOM requirements. The synchronous rendering model distinguishes it from standard Mermaid, making it particularly valuable for chat interfaces and CLI tools where immediate visual feedback matters.
The project maintains a substantial base of adopters who report real-world use cases through open issues. Response times to issues and pull requests typically range from one to two weeks.
