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

yarn add mermaid

pnpm add 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:

Import Mermaid

Import the Mermaid library in your JavaScript file:

app.js

import mermaid from 'mermaid';

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')

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);
}

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.

Getting Started

Core Concepts

Diagram Types

Configuration

Advanced

Quickstart

Quickstart

Step 1: Install Mermaid

Step 2: Create your HTML file

Step 3: Initialize and render

Example: Complete application

Common patterns

Parsing diagrams

Error handling

Detecting diagram types

Next steps

Diagram syntax

Configuration

API reference

Examples

​Quickstart

​Step 1: Install Mermaid

​Step 2: Create your HTML file

​Step 3: Initialize and render

​Example: Complete application

​Common patterns

​Parsing diagrams

​Error handling

​Detecting diagram types

​Next steps

Diagram syntax

Configuration

API reference

Examples

Quickstart

Step 1: Install Mermaid

Step 2: Create your HTML file

Step 3: Initialize and render

Example: Complete application

Common patterns

Parsing diagrams

Error handling

Detecting diagram types

Next steps