beautiful_mermaid

Render beautiful Mermaid diagrams in Flutter. Powered by beautiful-mermaid — a zero-DOM, pure TypeScript Mermaid renderer that outputs clean, styled SVGs.

Supports flowcharts, sequence diagrams, state diagrams, class diagrams, and ER diagrams with 15 built-in themes and pan/zoom controls.

Quickstart

1. Add the dependency

dependencies:
  beautiful_mermaid: ^0.1.0

2. Drop in a diagram

import 'package:beautiful_mermaid/beautiful_mermaid.dart';

MermaidDiagram(
  source: 'graph TD; A --> B --> C',
  colors: MermaidTheme.tokyoNight,
)

That's it — the widget handles rendering, JS library loading, and pan/zoom automatically.

How It Works

On Android, iOS, and macOS, MermaidDiagram embeds a lightweight WebView that loads the beautiful-mermaid JS library once from CDN. On web, it uses an HtmlElementView with an iframe and dart:js_interop — no WebView needed.

Subsequent diagram or theme changes are applied via JavaScript calls — no page reloads, no flashing.

Pan & Zoom

Pan and zoom is enabled by default. Controls include:

Gesture	Action
Scroll wheel / trackpad	Zoom in/out (centered on cursor)
Click and drag	Pan the diagram
Pinch (touch)	Zoom in/out
Double-click / double-tap	Fit to screen
Floating buttons	+, −, fit-to-screen

Disable pan/zoom

MermaidDiagram(
  source: 'graph TD; A --> B',
  panZoom: false,
)

Move the controls

MermaidDiagram(
  source: 'graph TD; A --> B',
  controlsPosition: MermaidControlsPosition.topRight,
)

Available positions: topLeft, topCenter, topRight, centerLeft, centerRight, bottomLeft, bottomCenter, bottomRight.

API Reference

MermaidDiagram

Parameter	Type	Default	Description
source	String	required	Mermaid diagram source text
colors	MermaidColors	MermaidTheme.zincLight	Color theme
font	String	'Inter'	Font family for diagram text
padding	double	40	Padding around the diagram (px)
transparent	bool	false	Transparent background
panZoom	bool	true	Enable pan/zoom controls
controlsPosition	MermaidControlsPosition	bottomRight	Position of +/−/fit buttons
onRendered	VoidCallback?	null	Called when rendering completes
onError	ValueChanged<String>?	null	Called on render error
loading	Widget?	CircularProgressIndicator	Custom loading widget
errorBuilder	Widget Function(String)?	null	Custom error widget

MermaidColors

Define custom color schemes:

MermaidDiagram(
  source: 'graph LR; A --> B',
  colors: MermaidColors(
    bg: Color(0xFF1a1a2e),
    fg: Color(0xFFe0e0e0),
    line: Color(0xFF404060),
    accent: Color(0xFF00d2ff),
    muted: Color(0xFF6c7086),
    surface: Color(0xFF252540),
    border: Color(0xFF353560),
  ),
)

Only bg and fg are required — they produce a clean monochrome diagram. The optional colors (line, accent, muted, surface, border) add richer visual hierarchy.

Themes

15 built-in themes are available via MermaidTheme:

Theme	Constant
Zinc Light	MermaidTheme.zincLight
Zinc Dark	MermaidTheme.zincDark
Tokyo Night	MermaidTheme.tokyoNight
Tokyo Night Storm	MermaidTheme.tokyoNightStorm
Tokyo Night Light	MermaidTheme.tokyoNightLight
Catppuccin Mocha	MermaidTheme.catppuccinMocha
Catppuccin Latte	MermaidTheme.catppuccinLatte
Nord	MermaidTheme.nord
Nord Light	MermaidTheme.nordLight
Dracula	MermaidTheme.dracula
GitHub Light	MermaidTheme.githubLight
GitHub Dark	MermaidTheme.githubDark
Solarized Light	MermaidTheme.solarizedLight
Solarized Dark	MermaidTheme.solarizedDark
One Dark	MermaidTheme.oneDark

Access all themes as a map:

// Iterate over all themes
for (final entry in MermaidTheme.all.entries) {
  print('${entry.key}: ${entry.value}');
}

// Look up by name
final colors = MermaidTheme.all['tokyo-night']!;

Diagram Types

Flowchart

MermaidDiagram(
  source: '''graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Other Action]''',
  colors: MermaidTheme.catppuccinMocha,
)

Sequence Diagram

MermaidDiagram(
  source: '''sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: Request
    B-->>A: Response''',
  colors: MermaidTheme.nord,
)

State Diagram

MermaidDiagram(
  source: '''stateDiagram-v2
    [*] --> Idle
    Idle --> Loading : fetch()
    Loading --> Success : done
    Loading --> Error : fail''',
  colors: MermaidTheme.dracula,
)

Class Diagram

MermaidDiagram(
  source: '''classDiagram
    class Animal {
      +String name
      +makeSound() void
    }
    class Dog {
      +fetch() void
    }
    Animal <|-- Dog''',
  colors: MermaidTheme.githubDark,
)

ER Diagram

MermaidDiagram(
  source: '''erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains''',
  colors: MermaidTheme.solarizedDark,
)

Platform Setup

The JS library is loaded from CDN, so internet access is required on first load. Each platform has a different rendering backend:

Platform	Backend	Notes
Android	WebView (webview_flutter)	Needs INTERNET permission
iOS	WKWebView (webview_flutter)	Works out of the box
macOS	WKWebView (webview_flutter)	Needs network entitlement
Web	HtmlElementView + iframe	No WebView — uses dart:js_interop directly
Windows/Linux	Not supported	webview_flutter has no implementation

Android

Add internet permission to android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- ... -->
</manifest>

iOS

No additional configuration needed.

macOS

macOS apps are sandboxed. Enable outgoing network connections in both entitlement files:

macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<key>com.apple.security.network.client</key>
<true/>

Web

No additional configuration needed. The package automatically uses an HtmlElementView with an iframe and communicates via postMessage — no WebView plugin required.

Tips

• Avoid using ValueKey on MermaidDiagram — this forces the widget to recreate the rendering context on every change. The widget already handles source/theme updates efficiently via JavaScript calls.

• The first render takes slightly longer because the JS library loads from CDN. After that, all updates are near-instant.

• Custom loading widget:

  MermaidDiagram(
    source: 'graph TD; A --> B',
    loading: Center(child: Text('Rendering...')),
  )

• Error handling:

  MermaidDiagram(
    source: invalidSource,
    onError: (error) => debugPrint('Mermaid error: $error'),
    errorBuilder: (error) => Center(child: Text('Failed: $error')),
  )

License

MIT — see LICENSE.