<mermaid-element>

graph LR HTML[Raw HTML Syntax] --> Element[<mermaid-element> Custom Element] Element --> Engine[Mermaid 12 via jsDelivr CDN] Engine --> SVG[Rendered SVG in Shadow DOM]

<mermaid-element>
    graph LR
        HTML[Raw HTML Syntax] --> Element[&lt;mermaid-element&gt; Custom Element]
        Element --> Engine[Mermaid 12 via jsDelivr CDN]
        Engine --> SVG[Rendered SVG in Shadow DOM]
    </mermaid-element>

Install mermaid-element alone. It will dynamically fetch Mermaid 12 on demand without bloating your node_modules:

npm install mermaid-element

import 'mermaid-element'; // Automatically registers <mermaid-element>

If your application bundles Mermaid locally or runs in an air-gapped environment, install both packages and assign your instance:

npm install mermaid-element mermaid

import mermaid from 'mermaid';
    import { MermaidElement } from 'mermaid-element';
    
    // Direct <mermaid-element> to use your local bundled Mermaid library
    MermaidElement.defaultMermaid = mermaid;

Include the module directly in any HTML document without build tools:

<script type="module" src="https://cdn.jsdelivr.net/npm/mermaid-element/index.js"></script>

By default, <mermaid-element> dynamically loads Mermaid 12 on demand from jsDelivr (see Example 1).

Authors can override this per element using the mermaid attribute:

• Version String: Pass a release version like mermaid="10.9.8" to fetch that release on demand from the CDN (see Example 2).
• Full URL or Path: Pass a full URL or relative path like mermaid="https://.../mermaid.esm.min.mjs" to load from a custom endpoint or self-hosted asset (see Example 3).

If your application already bundles Mermaid or operates in an offline / air-gapped environment, you can supply your own default instance instead of fetching from a CDN:

import mermaid from 'mermaid';
import { MermaidElement } from 'mermaid-element';

// Use your pre-installed or pre-configured instance as the default
MermaidElement.defaultMermaid = mermaid;

For script-based setups, <mermaid-element> also automatically detects a globally defined window.mermaid. Individual elements can still override this default by specifying their own mermaid attribute.

Format the raw Mermaid syntax as a readable monospace code block until the component upgrades:

mermaid-element:not(:defined) {
  display: block;
  white-space: pre-wrap;
  font-family: monospace;
}

Hide <mermaid-element> elements completely until they are registered in the CustomElementRegistry:

mermaid-element:not(:defined) {
  display: none;
}

<mermaid-element> exposes internal structural elements via the part attribute so you can style them from your page stylesheet using ::part():

/* Style the diagram container */
mermaid-element::part(container) {
  padding: 1.5rem;
  background: var(--bg-surface-elevated);
  border-radius: 8px;
}

/* Customize the error box */
mermaid-element::part(error) {
  border-color: #ef4444;
  background-color: #fef2f2;
}

graph TD subgraph Frontend [Client Tier] Web[Web Browser] Mobile[Mobile App] end subgraph Backend [Server Infrastructure] LB[Load Balancer] API1[API Server 1] API2[API Server 2] end subgraph Storage [Database Tier] DB[(Primary Database)] Cache[(Redis Cache)] end Web --> LB Mobile --> LB LB --> API1 LB --> API2 API1 --> DB API2 --> DB API1 --> Cache API2 --> Cache

<mermaid-element>
graph TD
    subgraph Frontend [Client Tier]
        Web[Web Browser]
        Mobile[Mobile App]
    end
    ...
</mermaid-element>

sequenceDiagram autonumber actor Customer actor Cashier participant Inventory participant PaymentGateway Customer->>Cashier: Hands items to purchase Cashier->>Inventory: Scan barcodes Inventory-->>Cashier: Price & stock confirmed Cashier->>Customer: Request payment Customer->>PaymentGateway: Tap credit card PaymentGateway-->>Customer: Transaction approved Cashier-->>Customer: Receipt issued

<mermaid-element mermaid="10.9.8">
sequenceDiagram
    autonumber
    actor Customer
    actor Cashier
    ...
</mermaid-element>

stateDiagram-v2 [*] --> Draft Draft --> InReview : Submit for Review InReview --> Approved : Approve InReview --> Draft : Request Changes Approved --> Published : Deploy Published --> [*]

<mermaid-element mermaid="https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.min.mjs">
stateDiagram-v2
    [*] --> Draft
    ...
</mermaid-element>

<mermaid-element>
graph TD
    A[Client Request] --> B[API Gateway]
    B --> C{Authentication}
    ...
</mermaid-element>

invalid diagram syntax this should trigger the error boundary

<mermaid-element>
  <template>
flowchart LR
    A["Raw & Unescaped <b>HTML</b>"] --> B["<tag>Node B</tag>"]
    B --> C["Node C"]
  </template>
</mermaid-element>

graph LR Client[Browser Client] --> LB[Load Balancer] LB --> App1[App Server 1] LB --> App2[App Server 2]

/* Page CSS */
mermaid-element.styled-part-example::part(container) {
  padding: 1.5rem;
  background: var(--bg-surface-elevated);
  border: 2px dashed var(--primary-color);
  border-radius: 10px;
}

<mermaid-element class="styled-part-example">
graph LR
    Client[Browser Client] --> LB[Load Balancer]
    LB --> App1[App Server 1]
    LB --> App2[App Server 2]
</mermaid-element>