sandboxBaseUrl Feature Demo

New Feature: sandboxBaseUrl Configuration Option

This page demonstrates the new sandboxBaseUrl configuration option for Mermaid.js, which enables relative URL resolution when using securityLevel: 'sandbox'.

The Problem

When Mermaid renders diagrams with securityLevel: 'sandbox', the SVG is embedded inside an iframe using a data: URI. This provides strong security isolation but creates a problem: relative URLs in clickable links don't work.

This happens because data: URIs have no base URL context. When you click a link like ./page.html inside a data URI iframe, the browser has no way to resolve what ./ refers to.

The Solution

The sandboxBaseUrl option tells Mermaid what base URL to use for resolving relative links. Before embedding the SVG in the sandbox iframe, Mermaid pre-resolves all relative URLs to absolute URLs using this base.

Configuration

Add sandboxBaseUrl to your Mermaid configuration:

mermaid.initialize({
  startOnLoad: true,
  securityLevel: 'sandbox',
  sandboxBaseUrl: window.location.href,  // or any absolute URL
  flowchart: { htmlLabels: false }       // recommended for sandbox mode
});
Option Type Description
sandboxBaseUrl string Base URL for resolving relative links. Only applies when securityLevel is 'sandbox'.
flowchart.htmlLabels boolean Set to false for sandbox mode. When true (default), labels use <foreignObject> with HTML, which doesn't render in data: URI iframes due to security restrictions. Setting to false uses pure SVG text instead.
Note: This option only affects sandbox mode. In other security levels (strict, loose, antiscript), relative URLs work normally because the SVG is rendered directly in the page context.

Interactive Demo

Test 1: Relative Link Resolution

Click "Index Page" to test relative URL resolution (opens ./index.html):

flowchart LR
    A[This Page] --> B[Index Page]
    A --> C[GitHub]

    click B "./index.html" "Relative link - should open index.html"
    click C "https://github.com/mermaid-js/mermaid" "Absolute link - opens GitHub"

Without sandboxBaseUrl, clicking "Index Page" would fail silently.

Test 2: Hash/Anchor Links

Click to jump to different sections of this page:

flowchart TD
    A["#problem"] --> B["#solution"]
    B --> C["#configuration"]
    C --> D["#url-types"]
    D --> E["#demo"]

    click A "#problem" "Jump to Problem section"
    click B "#solution" "Jump to Solution section"
    click C "#configuration" "Jump to Configuration section"
    click D "#url-types" "Jump to URL Types section"
    click E "#demo" "Jump to Demo section"

Test 3: Various URL Patterns

This diagram shows different URL types that are handled:

flowchart TD
    A["Relative: ./index.html"] --> B["Hash: #url-types"]
    B --> C["Absolute: https://mermaid.js.org"]

    click A "./index.html" "Relative URL - resolved using sandboxBaseUrl"
    click B "#url-types" "Hash URL - jumps to section below"
    click C "https://mermaid.js.org" "Absolute URL - unchanged, opens directly"

URL Types Handled

You navigated here! If you clicked a hash link from the diagram above, it worked correctly.
URL Pattern Example Behavior
Relative ./page.html, ../parent.html Resolved against sandboxBaseUrl
Root-relative /absolute/path.html Resolved against origin of sandboxBaseUrl
Hash/Anchor #section-id Resolved against sandboxBaseUrl
Absolute https://example.com Unchanged (already absolute)
Protocol-relative //example.com/path Unchanged (already absolute)
Special protocols mailto:, tel:, javascript: Unchanged

Implementation Details

The feature works by:

  1. Rendering the SVG to a live DOM element
  2. Finding elements with href and xlink:href attributes using querySelectorAll
  3. Resolving relative URLs directly on the DOM using JavaScript's URL constructor
  4. Extracting innerHTML (with URLs already resolved)
  5. Embedding the SVG in the sandbox iframe

This DOM-based approach avoids parsing and re-serializing the SVG string, and has zero overhead when sandboxBaseUrl is not configured.

Source Code

This feature is implemented in the main Mermaid.js repository. The key files are: