Mermaid Click Events: Build Interactive Diagrams (Complete Tutorial)

# Mermaid Click Events: Build Interactive Diagrams (Complete Tutorial)

Static diagrams tell a story. Interactive diagrams let users explore one. Mermaid.js supports click events that turn any node into a clickable link or a JavaScript callback trigger — perfect for navigation maps, architecture explorers, runbooks, and dashboards.

This guide covers everything you need to know about Mermaid click events: syntax, security levels, real-world examples, and the gotchas that trip up most developers.

What Are Mermaid Click Events?

A click event binds a node in your Mermaid diagram to one of two actions:

1. Open a URL when the node is clicked
2. Call a JavaScript function with the node ID as an argument

This works in flowcharts, class diagrams, state diagrams, and several other Mermaid diagram types. With one line of syntax, your diagram becomes a navigable interface.

Basic Syntax: Linking Nodes to URLs

The simplest click event opens a URL in the same tab:

flowchart LR
    A[Home] --> B[Docs]
    B --> C[API Reference]
    B --> D[Tutorials]

    click A "https://mermaideditor.lol" "Visit homepage"
    click B "https://mermaid.js.org/intro/" "Read the docs"
    click C "https://mermaid.js.org/syntax/flowchart.html" "API reference"
    click D "https://mermaideditor.lol/blog" "Browse tutorials"

The pattern is:

click <nodeId> "<url>" "<tooltip>"

The tooltip is optional but highly recommended — it appears on hover and improves accessibility.

Opening Links in a New Tab

Use the _blank target to open the URL in a new browser tab:

flowchart TD
    A[Dashboard] --> B[GitHub]
    A --> C[Docs Site]

    click B "https://github.com" "GitHub" _blank
    click C "https://mermaideditor.lol" "Docs" _blank

Valid targets: _self, _blank, _parent, _top.

JavaScript Callbacks

You can also trigger a JavaScript function when a node is clicked. The function receives the node ID as its first argument:

flowchart LR
    A[Order Created] --> B[Payment Pending]
    B --> C[Shipped]
    C --> D[Delivered]

    click A callback "View order details"
    click B callback "View payment status"
    click C callback "Track shipment"
    click D callback "Confirm delivery"

In your host page, define the callback:

window.callback = function(nodeId) {
  console.log('Clicked node:', nodeId);
  showModal(nodeId);
};

You can also pass extra arguments:

click A myFunc "tooltip" arg1 arg2

The Security Level Gotcha

This is where most developers get stuck. By default, Mermaid runs with securityLevel: "strict", which disables click events that call JavaScript callbacks. URL clicks still work, but custom functions won't fire.

To enable callbacks, configure Mermaid like this:

import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  securityLevel: 'loose', // required for callbacks
});

Security Levels Explained

Rule of thumb: Use loose only when you control the diagram source. Never use it for user-submitted Mermaid code.

Real-World Example: Clickable Architecture Diagram

A practical use case — turn a system architecture diagram into a navigable map where each service links to its README:

flowchart TB
    subgraph Frontend
        Web[Next.js Web App]
        Mobile[React Native App]
    end

    subgraph Backend
        API[REST API]
        Auth[Auth Service]
        Worker[Background Worker]
    end

    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
        Queue[RabbitMQ]
    end

    Web --> API
    Mobile --> API
    API --> Auth
    API --> DB
    API --> Cache
    API --> Queue
    Queue --> Worker
    Worker --> DB

    click Web "https://github.com/org/web" "Web app repo" _blank
    click Mobile "https://github.com/org/mobile" "Mobile repo" _blank
    click API "https://github.com/org/api" "API repo" _blank
    click Auth "https://github.com/org/auth" "Auth service repo" _blank
    click Worker "https://github.com/org/worker" "Worker repo" _blank

Now your architecture diagram doubles as a service catalog. New engineers click a box and land on the right repo.

Click Events in Class Diagrams

Mermaid class diagrams support clicks too — useful for linking classes to source files or API docs:

classDiagram
    class User {
        +String email
        +login()
        +logout()
    }
    class Order {
        +Number total
        +place()
    }
    User --> Order : places

    click User "https://github.com/org/app/blob/main/models/user.ts" "User model source"
    click Order "https://github.com/org/app/blob/main/models/order.ts" "Order model source"

Click Events in State Diagrams

State diagrams can link each state to its handler documentation:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing
    Processing --> Completed
    Processing --> Failed
    Completed --> [*]
    Failed --> [*]

    click Pending "/docs/states/pending" "Pending state docs"
    click Processing "/docs/states/processing" "Processing logic"
    click Failed "/docs/states/failed" "Failure recovery"

Common Pitfalls

1. Clicks not firing in GitHub READMEs

GitHub renders Mermaid with strict security and strips click handlers entirely. Click events only work in your own apps and docs sites where you control the Mermaid config.

2. "click" recognized as a node

Make sure the click directive is on its own line, not inside a node definition. The parser is whitespace sensitive.

3. Tooltips not showing

Tooltips require the URL or callback to be present first. The order is: click .

4. URLs with special characters

Wrap URLs in double quotes and URL-encode query strings. Spaces especially will break parsing.

5. Callbacks not defined yet

Mermaid renders before your script runs? Define callbacks on window before calling mermaid.run(), or use startOnLoad: false and trigger rendering manually.

Styling Clickable Nodes

Signal that a node is clickable using a classDef:

flowchart LR
    A[Home] --> B[Docs]
    B --> C[API]

    classDef clickable fill:#dbeafe,stroke:#2563eb,color:#1e3a8a,cursor:pointer
    class A,B,C clickable

    click A "/" "Home"
    click B "/docs" "Documentation"
    click C "/api" "API reference"

The cursor:pointer style is the visual cue users expect.

When to Use Click Events

Great fits:

• Service catalogs — architecture diagrams that link to repos
• Runbooks — flowcharts where each step links to a Slack channel or wiki page
• API maps — endpoint diagrams linking to OpenAPI docs
• Onboarding diagrams — clickable org charts or product tours
• Roadmaps — milestone nodes linking to GitHub projects or Linear issues

When not to bother:

- Static images exported to PDF or PNG (clicks don't survive export)

- GitHub README diagrams (strict mode strips them)

- Print materials

Conclusion

Click events are one of Mermaid's most underused features. With one extra line per node, you can transform a flat diagram into a navigation interface — no extra libraries, no SVG editing, no JavaScript framework required.

Start with simple URL links, graduate to JavaScript callbacks once you need richer interactions, and remember to set securityLevel: "loose" only on trusted content.

Try interactive Mermaid diagrams in our free editor →