Skip to main content

​
Quickstart

This guide will help you create and render your first Mermaid diagram. You’ll learn the basic workflow for integrating Mermaid into your project.

​
Step 1: Install Mermaid

First, install Mermaid in your project: 
npm install mermaid
Alternatively, you can use the CDN approach if you want to skip the installation. See the installation guide for details.

​
Step 2: Create your HTML file

Create an HTML file with a div element that will contain your diagram. Use the class mermaid to mark elements for automatic rendering:
index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Mermaid Diagram</title>
</head>
<body>
  <h1>My First Mermaid Diagram</h1>
  
  <div class="mermaid">
    graph LR
      A[Start] --> B{Is it working?}
      B -->|Yes| C[Great!]
      B -->|No| D[Check the console]
      C --> E[End]
      D --> E[End]
  </div>

  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</body>
</html>
The mermaid.initialize() function configures Mermaid. Setting startOnLoad: true tells Mermaid to automatically render all diagrams when the page loads.

​
Step 3: Initialize and render

If you’re using Mermaid in a JavaScript application, here’s how to initialize and render diagrams programmatically:
1

Import Mermaid

Import the Mermaid library in your JavaScript file:
app.js
import mermaid from 'mermaid';
2

Initialize Mermaid

Configure Mermaid with the initialize() function. This should be done before rendering:
app.js
mermaid.initialize({
  startOnLoad: true,
  theme: 'default',
  logLevel: 'error',
});
Common configuration options:
  • startOnLoad: Automatically render diagrams on page load (default: true)
  • theme: Visual theme ('default', 'dark', 'forest', 'neutral')
  • logLevel: Console logging level ('debug', 'info', 'warn', 'error', 'fatal')
3

Render diagrams

For automatic rendering, Mermaid will find all elements with the class mermaid and render them:
app.js
// This happens automatically when startOnLoad is true
await mermaid.run();
For manual rendering of a specific diagram:
app.js
const element = document.querySelector('#myDiagram');
const graphDefinition = `
  graph TB
    A[Start] --> B[Process]
    B --> C[End]
`;

const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
element.innerHTML = svg;

// Bind any interactive functions (e.g., click handlers)
if (bindFunctions) {
  bindFunctions(element);
}
4

View your diagram

Open your HTML file in a browser. You should see your diagram rendered!

​
Example: Complete application

Here’s a complete example showing different ways to use Mermaid:
complete-example.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Mermaid Examples</title>
</head>
<body>
  <h1>Mermaid Diagram Examples</h1>
  
  <!-- Automatic rendering with class="mermaid" -->
  <h2>Sequence Diagram</h2>
  <div class="mermaid">
    sequenceDiagram
      Alice->>John: Hello John, how are you?
      loop HealthCheck
        John->>John: Fight against hypochondria
      end
      Note right of John: Rational thoughts!
      John-->>Alice: Great!
      John->>Bob: How about you?
      Bob-->>John: Jolly good!
  </div>
  
  <!-- Manual rendering -->
  <h2>Flowchart</h2>
  <div id="manualDiagram"></div>

  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    
    // Initialize mermaid
    mermaid.initialize({
      startOnLoad: true,
      theme: 'default'
    });
    
    // Manual rendering example
    const diagram = `
      flowchart LR
        A[Hard] -->|Text| B(Round)
        B --> C{Decision}
        C -->|One| D[Result 1]
        C -->|Two| E[Result 2]
    `;
    
    const { svg } = await mermaid.render('manualId', diagram);
    document.getElementById('manualDiagram').innerHTML = svg;
  </script>
</body>
</html>

​
Common patterns

​
Parsing diagrams

Validate diagram syntax without rendering: 
const diagramText = 'graph TD\n  A-->B';

try {
  const result = await mermaid.parse(diagramText);
  console.log('Valid diagram:', result.diagramType);
  // Output: { diagramType: 'flowchart-v2' }
} catch (error) {
  console.error('Invalid diagram:', error);
}

​
Error handling

Handle rendering errors gracefully: 
await mermaid.run({
  querySelector: '.mermaid',
  suppressErrors: true, // Don't throw errors, just log them
  postRenderCallback: (id) => {
    console.log('Rendered diagram:', id);
  }
});

​
Detecting diagram types

const diagramText = 'sequenceDiagram\n  Alice->>Bob: Hello';
const type = await mermaid.detectType(diagramText);
console.log(type); // 'sequence'

​
Next steps

Now that you’ve created your first diagram, explore more advanced topics:

Diagram syntax

Learn the syntax for different diagram types

Configuration

Customize themes, styling, and behavior

API reference

Explore the complete Mermaid API

Examples

Browse real-world diagram examples
Try the Mermaid Live Editor to experiment with different diagram types and see the results in real-time.

Build docs developers (and LLMs) love

Get started for freeTalk to us