flowchart LR
A[Start] --> B{Decision}
B -->|Yes| C[Do Thing]
B -->|No| D[Skip]
C --> E[Done]
D --> E
```
Open that file in any modern browser. You'll see a rendered flowchart with boxes, arrows, and labels — no build step, no server.
> [!TIP]
> The fastest way to experiment is the [Mermaid Live Editor](https://mermaid.live). Paste diagram text on the left, see the rendered SVG on the right, and export as SVG or PNG.
### How It Works
1. Mermaid scans the page for elements with `class="mermaid"` (or a selector you configure).
2. It parses the text content of each element as diagram syntax.
3. It replaces the text with a rendered SVG.
That's the entire model. No compilation, no external service, no image files to manage. The diagram definition IS the source of truth.
### Diagram in Markdown (GitHub, GitLab, Docusaurus)
Most platforms that support Mermaid use fenced code blocks:
````markdown
```mermaid
flowchart TD
A[User Request] --> B[Load Balancer]
B --> C[App Server 1]
B --> D[App Server 2]
C --> E[(Database)]
D --> E
```
````
GitHub renders this natively in issues, PRs, and Markdown files — no plugin needed.
---
## 2. Installation
### npm / yarn / pnpm
**npm:**
```bash
npm install mermaid
```
**yarn:**
```bash
yarn add mermaid
```
**pnpm:**
```bash
pnpm add mermaid
```
Then import in your JavaScript/TypeScript:
```javascript
import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: true });
```
### CDN (No Build Step)
Use the ESM build from jsDelivr:
```html
```
Or pin to an exact version:
```html
```
> [!IMPORTANT]
> Always use `type="module"` with the ESM build. Without it, the browser treats the script as a classic script and the `import` statement fails with a syntax error.
> [!WARNING]
> The UMD build (`mermaid.min.js`) is still available but the ESM build (`mermaid.esm.min.mjs`) is the recommended path for new projects. The UMD build attaches `mermaid` to `window` globally.
### Requirements
| Requirement | Minimum |
|---|---|
| Node.js (for npm install) | 18+ |
| Browser | Any modern browser with ES module support (Chrome 61+, Firefox 60+, Safari 11+, Edge 79+) |
| Package manager | npm 7+, yarn 1.22+, or pnpm 7+ |
### Using with Bundlers
Mermaid works with Webpack, Vite, Rollup, and esbuild. No special configuration is needed — import and call `initialize()`.
**Vite example (vite.config.js):**
```javascript
// No special mermaid config needed — works out of the box
export default {
// your normal vite config
};
```
**Webpack note:** If you encounter issues with Webpack 4, upgrade to Webpack 5 or use the CDN approach.
### Using with Frameworks
**React:**
```jsx
import { useEffect, useRef } from 'react';
import mermaid from 'mermaid';
function MermaidDiagram({ chart }) {
const ref = useRef(null);
useEffect(() => {
mermaid.initialize({ startOnLoad: false });
mermaid.run({ nodes: [ref.current] });
}, [chart]);
return {chart};
}
```
**Vue 3:**
```vue
{{ code }}
```
---
## 3. Configuration
Mermaid's behavior is controlled through a configuration object passed to `mermaid.initialize()`. Configuration can also be set per-diagram using directives.
### Global Configuration
```javascript
mermaid.initialize({
theme: 'default',
look: 'classic',
securityLevel: 'strict',
startOnLoad: true,
logLevel: 'warn', // 0=trace, 1=debug, 2=info, 3=warn, 4=error, 5=fatal
fontFamily: 'sans-serif',
fontSize: 16,
maxTextSize: 50000,
maxEdges: 500,
htmlLabels: true,
darkMode: false,
deterministicIds: false,
suppressErrorRendering: false,
wrap: false,
});
```
### Top-Level Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
| `theme` | string | `'default'` | Color theme. See Themes section below. |
| `look` | string | `'classic'` | Visual style: `'classic'`, `'handDrawn'`, `'neo'` |
| `layout` | string | `'dagre'` | Layout algorithm: `'dagre'` or `'elk'` |
| `securityLevel` | string | `'strict'` | Controls HTML/script handling. See Security section. |
| `startOnLoad` | boolean | `true` | Auto-render `class="mermaid"` elements on page load |
| `logLevel` | number/string | `3` (warn) | Logging verbosity (0=trace through 5=fatal) |
| `fontFamily` | string | `'sans-serif'` | Base font for all text |
| `fontSize` | number | `16` | Base font size in pixels |
| `maxTextSize` | number | `50000` | Maximum characters in a single diagram definition |
| `maxEdges` | number | `500` | Maximum edges before rendering is refused |
| `htmlLabels` | boolean | `true` | Use HTML (`
flowchart LR
A --> B
sequenceDiagram
Alice->>Bob: Hi
pie title Distribution
"A" : 40
"B" : 60
```
### Recipe 25: Using ELK Layout for Complex Graphs
```
%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TD
A --> B & C & D
B --> E
C --> E & F
D --> F & G
E --> H
F --> H
G --> H
```
### Recipe 26: Responsive Diagrams with useMaxWidth
```javascript
mermaid.initialize({
flowchart: { useMaxWidth: true },
sequence: { useMaxWidth: true },
});
```
This makes diagrams scale to fit their container width instead of using a fixed size.
### Recipe 27: Register Custom Icon Packs
```javascript
const iconPack = {
prefix: 'custom',
icons: {
server: { body: '` tags but not in `` tags **Cause:** By default Mermaid looks for elements with `class="mermaid"`. Both `` and `` work, but the selector must match. **Fix:** Either use `class="mermaid"` on your elements, or call `mermaid.run()` with a custom selector: ```javascript await mermaid.run({ querySelector: '.my-diagram', }); ``` ### Problem: SVG is cut off or clipped **Cause:** The container has constrained dimensions and `useMaxWidth` is `true`. **Fix:** Ensure the container can expand, or set `useMaxWidth: false` for fixed-size output: ```javascript mermaid.initialize({ flowchart: { useMaxWidth: false }, }); ``` ### Problem: Diagram renders but text is garbled or missing **Cause:** The specified font is not available in the browser. **Fix:** Use a web-safe font or load the font before Mermaid renders: ```javascript mermaid.initialize({ fontFamily: '"Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif', }); ``` ### Problem: ELK layout produces unexpected node positions **Cause:** ELK has different layout defaults than Dagre. Node order in the definition matters more with ELK. **Fix:** Use ELK-specific options: ```javascript mermaid.initialize({ flowchart: { defaultRenderer: 'elk', elk: { nodePlacementStrategy: 'NETWORK_SIMPLEX', forceNodeModelOrder: true, }, }, }); ``` ### Problem: Mermaid.run() throws "No elements found" **Cause:** Called before the DOM has the mermaid elements, or elements don't have `class="mermaid"`. **Fix:** Wait for DOM ready, or pass nodes explicitly: ```javascript document.addEventListener('DOMContentLoaded', () => { mermaid.run(); }); ``` ### Problem: Duplicate rendering — diagrams appear twice **Cause:** `startOnLoad: true` AND a manual `mermaid.run()` call — the diagram renders twice. **Fix:** Use one or the other: ```javascript // Option A: auto-render mermaid.initialize({ startOnLoad: true }); // Don't call mermaid.run() // Option B: manual render mermaid.initialize({ startOnLoad: false }); mermaid.run(); ``` ### Problem: Flowchart.htmlLabels setting has no effect **Cause:** `flowchart.htmlLabels` is deprecated. **Fix:** Use the top-level `htmlLabels` option: ```javascript mermaid.initialize({ htmlLabels: true, // Correct — top level // flowchart: { htmlLabels: true } // DEPRECATED — don't use }); ``` ### Problem: Diagram works in Live Editor but not on my page **Cause:** Version mismatch — the Live Editor may use a newer Mermaid version, or your page has conflicting CSS. **Fix:** 1. Check your Mermaid version matches the Live Editor version. 2. Inspect for CSS conflicts (especially `pre`, `code`, or SVG styles). 3. Check the browser console for parse errors. ### Problem: Gantt chart dates display incorrectly **Cause:** `dateFormat` doesn't match the date strings in your task definitions. **Fix:** Ensure format matches: ```mermaid gantt dateFormat YYYY-MM-DD section Tasks Task A :2026-01-15, 10d ``` If using `DD/MM/YYYY`, set `dateFormat DD/MM/YYYY`. ### Problem: Sandbox mode iframe has wrong dimensions **Cause:** When `securityLevel: 'sandbox'`, Mermaid renders in an iframe whose dimensions may not match the SVG content. **Fix:** Let the container control sizing. Avoid fixed heights on the parent element. Consider using `'strict'` or `'antiscript'` instead if iframe isolation isn't needed. > [!TIP] > For most documentation sites, `securityLevel: 'strict'` (the default) is the right choice. Reserve `'sandbox'` for cases where you need complete iframe isolation. ### Problem: Theme changes don't take effect after initialization **Cause:** `mermaid.initialize()` sets the config but doesn't re-render existing diagrams. **Fix:** After changing config, call `mermaid.run()` to re-render: ```javascript mermaid.initialize({ theme: 'dark' }); mermaid.run(); // Re-render with new theme ``` > [!WARNING] > Re-rendering replaces the SVG content of all matched elements. If you've attached event listeners directly to SVG elements, they will be lost on re-render. --- ## 7. FAQ **Q1: What diagram types does Mermaid support?** Mermaid supports 27 diagram types: flowchart, sequence, class, state, ER (entity-relationship), Gantt, pie, user journey, C4, mindmap, timeline, quadrant chart, XY chart, requirement, git graph, sankey, block, architecture, packet, kanban, ishikawa (fishbone), radar, venn, treemap, event modeling, tree view, and wardley map. Types marked "beta" (e.g., `sankey-beta`) are stable enough for production but the syntax may evolve. **Q2: Does Mermaid have a CLI?** No. Mermaid is a browser-side JavaScript library. There is a separate community project, `mermaid-cli` (`@mermaid-js/mermaid-cli`), which wraps Mermaid in Puppeteer to render diagrams from the command line — but that is a distinct package, not part of the core library. **Q3: Can I use Mermaid without npm/Node.js?** Yes. Use the CDN approach — a single `