Diagrams as Code. Vue 2. Mermaid.
Pass a Mermaid string — or a structured object — and get a rendered SVG diagram. Flowcharts, sequence, class, gantt, and more. Local files, remote URLs, or inline syntax.

@wbc-ui2/mermaid — Diagram as Code: pass a Mermaid string, get a rendered SVG

Architecture: Input sources (inline, file) feed @wbc-ui2/mermaid which renders to SVG

--- ## Why? **@wbc-ui2/mermaid** renders [Mermaid](https://mermaid.js.org/) diagrams from data. Drop in the diagram text and the component handles the async render, sizing, and error fallback — no manual `mermaid.run()` wiring. ### Render a diagram in one line ```html ``` ### Load it from a file or URL ```html ``` > **One component. One `` tag.** Inline syntax, an object, or a file path — the same prop. Everything is data. --- ## What is @wbc-ui2/mermaid? A **Vue 2.7+ component** — `` — that renders Mermaid diagrams as auto-sized SVG. Works standalone or as a plugin inside the `@wbc-ui2/core` (WBC) ecosystem. | Surface | Role | |---|---| | `` | The renderer — async-renders the Mermaid source to SVG with error fallback | | `src` | `String` (raw Mermaid syntax or a file path / URL) **or** `Object` (structured → auto-converted to syntax) | | `config` | Mermaid config object (theme, security level, flowchart options…) | | `wbcObj` | WBC wrapper config (card, title, caption…) when used inside `@wbc-ui2/core` | `src` accepts raw Mermaid text, an `http(s)` URL, a local `./file.mmd` (via `require.context`), a served `/file.mmd`, or a structured object the component converts to Mermaid syntax. Supports flowcharts, sequence, class, state, ER, gantt, pie, and the rest of the Mermaid grammar. **Who's it for?** Docs sites, architecture pages, runbooks, and any app that needs diagrams-as-code without bespoke Mermaid bootstrapping. --- ## Usage Examples ### Level 1 — Inline flowchart ```html ``` ### Level 2 — Sequence diagram with config ```html ``` ### Level 3 — Inside a WBC tree, styled ```html ``` --- ## 🚀 Try it in 30 seconds ```bash # Live interactive lab — paste any Mermaid syntax, see it render open https://mermaid2.wbc-ui.com ``` > Explore the grammar at **[mermaid2.wbc-ui.com](https://mermaid2.wbc-ui.com)** — paste a diagram, tweak the config, copy the snippet back to your project. --- ## Installation ### Prerequisites - **Node.js** ≥ 18 · **Vue 2.7.x** (Vue 3 tracked as `@wbc-ui3/mermaid`) - **[`mermaid`](https://www.npmjs.com/package/mermaid)** ≥ 11 (the diagram engine) - **[`@wbc-ui2/core`](https://www.npmjs.com/package/@wbc-ui2/core)** — optional; only needed for `wbcObj` wrapping / local-file loading ### npm (recommended) ```bash npm install @wbc-ui2/mermaid mermaid # Peer dependencies — install once per project npm install vue@^2.7.16 # Optional, for WBC integration: npm install @wbc-ui2/core ``` ### Yarn / pnpm ```bash yarn add @wbc-ui2/mermaid mermaid vue@^2.7.16 pnpm add @wbc-ui2/mermaid mermaid vue@^2.7.16 ``` ### Vue 2 plugin registration ```javascript // main.js import Vue from 'vue'; import WBMermaidPlugin from '@wbc-ui2/mermaid'; Vue.use(WBMermaidPlugin); // Optional — register @wbc-ui2/core first for wbcObj + local-file loading: // import wbcCore from '@wbc-ui2/core'; // Vue.use(wbcCore, { context: require.context('./src', true, /\.mmd$/) }); // Use anywhere in your app. ``` ### Troubleshooting common install errors | Symptom | Cause | Fix | |---|---|---| | `Cannot find module 'mermaid'` | `mermaid` is a peer dep, not bundled | `npm install mermaid@^11`. | | Diagram shows a parse error | Invalid Mermaid syntax | Validate at [mermaid.live](https://mermaid.live); the component renders the error inline. | | `WBC is not registered` (using `wbcObj`) | `@wbc-ui2/core` not registered | `Vue.use(wbcCore)` before `Vue.use(WBMermaidPlugin)`. | | Local `./file.mmd` won't load | `require.context` not provided to core2 | `Vue.use(wbcCore, { context: require.context('./src', true, /\.mmd$/) })`. | For worked examples, see [mermaid2.wbc-ui.com](https://mermaid2.wbc-ui.com). --- ## ⚡ The Component Under the Hood

Component architecture diagram

Component architecture: src prop -> parse input -> mermaid.js renderAsync -> SVG output

- **Async pipeline**: Offloads rendering to Mermaid's async engine to avoid blocking the main thread. - **Object-to-Syntax**: Accepts structured JS objects and automatically serializes them into valid Mermaid grammar. - **Resilient**: Gracefully catches syntax errors and displays them inline for rapid debugging. --- ## 💎 Free vs Pro > **`@wbc-ui2/mermaid` is open-source and a complete diagram component today** — the full Mermaid grammar, file/URL loading, config, and WBC integration are free. The Pro lane follows the same open-core tiering as the underlying [`@wbc-ui2/core`](https://www.npmjs.com/package/@wbc-ui2/core) engine. | Capability | Free | Pro | |---|---|---| | Full Mermaid grammar (flow, sequence, class, gantt, …) | ✅ Full | ✅ Full | | Inline syntax · object · file · URL sources | ✅ Full | ✅ Full | | Mermaid `config` + WBC integration (`wbcObj`) | ✅ | ✅ | | Depth / item caps on the rendered WBC tree | core2 free caps | ∞ (via core2 Pro) | | Advanced engine hooks & headless extraction | — | ✅ (via core2 Pro) | 👉 **[Compare in detail →](https://wbc-ui.com/free-vs-pro)** · **[Buy Pro →](https://wbc-ui.com/pricing)** --- ## 🌐 Ecosystem `@wbc-ui2/mermaid` is a sibling package in the **@wbc-ui2** monorepo. Every package is published to npm and shares the same versioning line. | Package | What it adds | Status | |---|---|---| | [`@wbc-ui2/core`](https://www.npmjs.com/package/@wbc-ui2/core) | "UI as Data" engine — the foundation | 🟢 GA | | [`@wbc-ui2/code`](https://www.npmjs.com/package/@wbc-ui2/code) | JSON-driven code editor + live run | 🟢 GA | | [`@wbc-ui2/chart`](https://www.npmjs.com/package/@wbc-ui2/chart) | ECharts integration | 🟢 GA | | [`@wbc-ui2/dataviewer`](https://www.npmjs.com/package/@wbc-ui2/dataviewer) | JSON / data-table explorer | 🟢 GA | | [`@wbc-ui2/latex`](https://www.npmjs.com/package/@wbc-ui2/latex) | LaTeX math rendering | 🟢 GA | | **[`@wbc-ui2/mermaid`](https://www.npmjs.com/package/@wbc-ui2/mermaid)** | **Diagram-as-code rendering** *(this package)* | 🟢 GA | | [`@wbc-ui2/alert`](https://www.npmjs.com/package/@wbc-ui2/alert) | Notification / toast system | 🟢 GA | | [`@wbc-ui2/press`](https://www.npmjs.com/package/@wbc-ui2/press) | Markdown-driven docs engine | 🟢 GA | --- ## Build artifacts | Format | File | |---|---| | ESM | `dist/mermaid2.es.js` | | UMD | `dist/mermaid2.umd.js` | --- ## 📄 License MIT © [Wissem Boughamoura](https://github.com/wissemb11) · [wi-bg.com](https://www.wi-bg.com) · [wbc-ui.com](https://wbc-ui.com)