Auto Modes

There is one player: the <mermaid-flow-player> custom element. Everything else is a way of getting your markup into it, so no route has features the others lack.

Entry	Best for	Loads Mermaid?
mermaid-flow-player.element.js	Writing <mermaid-flow-player> yourself	Yes (if missing)
auto.global.js	The diagrams already on your page — upgrades them in place	Yes (if missing)
auto-init.js	The same upgrade, but you choose when and what	Yes (if missing)

Auto mode runs the upgrade on load and again when an SPA swaps the DOM. Load auto.global.js in a <script> tag, or import auto.js when a bundler is doing the work. Import auto-init.js instead when you want to call it yourself.

Let the player render

The upgrade reads the diagram source out of the block, so Mermaid must not have replaced it with SVG first. Initialize Mermaid with startOnLoad: false, or just don’t load Mermaid at all and let the player fetch it.

A block that is already rendered still gets a player — its SVG is adopted rather than discarded — but narration falls back to node labels, because the %% narrate script went with the source text.

Upgrading the diagrams you already have

Add one script, and every diagram on the page becomes a player, keeping its id and your classes so your CSS and anchor links still resolve. Three shapes of markup are picked up with no configuration:

Your markup	Emitted by
<div class="mermaid"> / <pre class="mermaid">	hand-authored, Mermaid’s own docs
<pre><code class="language-mermaid">	markdown-it, marked, Prism, Jekyll, Hugo, Eleventy
<pre class="language-mermaid">	Shiki, Astro, Starlight, VitePress, Docusaurus

A fence carrying the class on both the <pre> and the <code> still produces one player, the whole <pre> is replaced rather than the <code> inside it, and language-* classes are left behind so your code styling does not follow the player.

<script src="https://cdn.jsdelivr.net/npm/mermaid-flow-player@latest/auto.global.js"></script>

<div class="mermaid">
graph LR
  A --> B --> C
</div>

Configure a block with the same attribute names the element uses, with or without a data-flow- prefix — both spellings work, so markup copied between the two routes keeps working:

<div class="mermaid" speed="2" captions autoplay trigger="scroll">
graph LR
  A --> B --> C
</div>

autoInit()

import { autoInit, destroyAll } from 'https://cdn.jsdelivr.net/npm/mermaid-flow-player@latest/auto-init.js';

const players = autoInit({
  selector: '.diagram',
  controls: 'play-pause next fit',
});

// Later: put the original blocks back
destroyAll();

Option	Description
selector	Which blocks to upgrade. Defaults to .mermaid, pre.language-mermaid and pre > code.language-mermaid.
controls	true (transport + zoom), false, a preset ("viewer", "full"), or an explicit token list.
narration	Render the caption area. Default true.
debug	Log indexing and narration mismatches.
queryConfig	Override the URL query defaults.

It returns the elements it created, so el.player gets you the underlying player API.

Web Component

Controls Options

controls takes a preset or an explicit space-separated token list. Tokens: play-pause, restart, previous, next, speed, all-paths, zoom-out, fit, zoom-in, fullscreen, focus, search, copy-svg, download-svg, open-svg.

None

Default Sequential Controls

Explicit Token List

Interactive Restart

Live Examples

With Narration

Auto-Play

Add trigger="scroll" and playback waits until the diagram is actually on screen, rather than finishing above the fold before anyone sees it.

Minimap

Choosing a Route

Route	Use case
<mermaid-flow-player>	New markup; full control over attributes
auto.global.js	A docs site or Markdown pipeline already emitting diagrams
autoInit()	The same upgrade, on your schedule or a custom selector
createFlowPlayer()	Driving playback yourself from JavaScript