API Reference

Complete reference for Mermaid Flow Player API.

CDN Import

<script type="module">
  import {
    createFlowPlayer,
    toAnimatedSvg,
    parseDiagram,
    bindGraph,
  } from 'https://cdn.jsdelivr.net/npm/mermaid-flow-player@latest/index.js';
</script>

Creates a new flow player instance.

Options

type FlowPlayerOptions = {
  root: HTMLElement;                      // Required: the diagram's container
  source: string;                         // Required: the Mermaid source
  narrationTarget?: HTMLElement | string; // Narration display element
  dim?: 'none' | 'others';                // Default: 'others'
  visited?: boolean;                      // Default: true
  easing?: EasingConfig;
  speed?: number;                         // Default: 1
  timing?: { stepMs: number };            // Default: 1200
  mode?: 'sequential' | 'interactive';
  debug?: boolean;
  hooks?: {
    onStepStart?: (step: Step, narration?: string) => void;
    onStepEnd?: (step: Step) => void;
    onError?: (err: unknown) => void;
    onPathChoice?: (availablePaths: string[]) => void;
  };
};

source is the diagram’s Mermaid text, and it is required. The player reads the diagram’s structure from it — never from the rendered SVG — which is why a step names the id you wrote (A, Still, Alice) rather than whatever id Mermaid stamped on the element. Auto mode and <mermaid-flow-player> pass it for you.

Example

<script type="module">
  import { createFlowPlayer } from 'https://cdn.jsdelivr.net/npm/mermaid-flow-player@latest/index.js';

  const diagram = document.getElementById('diagram');

  const player = createFlowPlayer({
    root: diagram,
    source: diagram.textContent,
    dim: 'others',
    speed: 1.5,
    debug: true
  });
</script>

FlowPlayer Methods

ready(): Promise<void>

Wait for diagram to be indexed. Must be called before play().

await player.ready();

play(scenario, options?): Promise<void>

Play an animation scenario.

await player.play(
  player.path('A', 'B', 'C'),
  { speed: 1.2, loop: false }
);

Play options:

Option	Type	Description
speed	number	Speed multiplier (default: 1.2)
loop	boolean	Loop the scenario

pause(): void

Pause the currently playing animation.

resume(): void

Resume a paused animation.

stop(): void

Stop the currently playing animation.

reset(options?): void

Reset diagram to initial state.

player.reset();
player.reset({ keepVisited: true });  // Keep visited state

index(): GraphIndex | null

Get the indexed nodes and edges.

const idx = player.index();
console.log(idx.nodes);  // Map<string, SVGGElement>
console.log(idx.edges);  // Map<string, SVGGElement>
console.log(idx.type);   // 'flowchart' | 'sequence' | 'state' | ...

path(…ids): Step[]

Create a scenario from node IDs.

const scenario = player.path('A', 'B', 'C');
await player.play(scenario);

assertIds(ids): void

Validate that all node IDs exist. Throws if any are missing.

player.assertIds(['A', 'B', 'C']);

destroy(): void

Clean up and remove all event listeners.

setStateNode(id, state, opts?): void

Manually set a node’s state.

player.setStateNode('A', 'active', { pulse: true, dimOthers: true });
player.setStateNode('B', 'success');
player.setStateNode('C', 'error');

States: 'idle' | 'active' | 'visited' | 'success' | 'error' | 'warning' | 'disabled'

setStateEdge(from, to, state, opts?): void

Manually set an edge’s state.

player.setStateEdge('A', 'B', 'active', { dimOthers: true });

Diagram-Specific Helpers

participant(id, opts?)

Highlight a participant in sequence diagrams.

const step = player.participant('Alice', { note: 'Initiator' });

message(from, to, opts?)

Highlight a message in sequence diagrams.

const step = player.message('Alice', 'Bob', { note: 'Request' });

state(id, opts?)

Highlight a state in state diagrams.

const step = player.state('Idle', { note: 'Initial state' });

transition(from, to, opts?)

Highlight a transition in state diagrams.

const step = player.transition('Idle', 'Active', { note: 'Start' });

Interactive Mode

Enable step-through with path selection:

const diagram = document.getElementById('diagram');
const player = createFlowPlayer({
  root: diagram,
  source: diagram.textContent,
  mode: 'interactive',
  hooks: {
    onPathChoice: (paths) => {
      console.log('Available paths:', paths);
    }
  }
});

await player.ready();

// Step through one node at a time
await player.nextStep();

// Check available paths from current node
const paths = player.getAvailablePaths();

// Choose a path
await player.selectPath('A->B');

// Get current position
const current = player.getCurrentNode();

Auto Modes

Both entry points do the same thing: upgrade .mermaid blocks into <mermaid-flow-player> elements. There is one player implementation, so the upgraded markup behaves exactly like element markup you wrote by hand.

Mermaid must not have rendered the blocks first — initialize it with startOnLoad: false, or let the player load Mermaid itself.

auto()

Zero config. Upgrades on load, and again when an SPA replaces the DOM.

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

stopAuto() disconnects the observer and restores the original blocks.

autoInit(options?)

The same upgrade, called on your terms. Returns the created elements.

<script type="module">
  import { autoInit } from 'https://cdn.jsdelivr.net/npm/mermaid-flow-player@latest/auto-init.js';

  const players = autoInit({
    selector: '.diagram',
    controls: 'play-pause next fit',
  });
  await players[0].ready();
  players[0].player.play();
</script>

Option	Type	Default
selector	string	.mermaid
controls	boolean | string	true
narration	boolean	true
debug	boolean	false
queryConfig	QueryConfig	parsed from the URL

destroyAll()

Replaces every upgraded element with the block it came from.

toAnimatedSvg(scenario, options?)

Draw a scenario as a standalone animated SVG: no script, nothing fetched, so it plays where the player cannot run at all — a README, a pull request comment, an email, a printed page.

const svg = player.toAnimatedSvg(
  [
    { type: 'node', id: 'A' },
    { type: 'edge', from: 'A', to: 'B' },
    { type: 'node', id: 'B' },
  ],
  { title: 'How a request is served' },
);

Option	Type	Default	What it does
stepMs	number	the player’s own step timing	How long a step lasts when it does not say
loop	boolean	true	false holds on the last step instead of repeating
title	string	none	The <title> a screen reader announces
accent	string	#3b82f6	The colour the current element is picked out in
restOpacity	number	0.28	How far back everything else is held

A reader whose system asks for less motion gets the finished diagram, still.

See Animated SVG for the whole story.

Step Types

// Node step
{ type: 'node', id: 'A', state: 'active', pulse: true, note: 'text', ms: 500 }

// Edge step. `key` names the exact arrow where a pair carries more than one,
// which `from`/`to` alone cannot: "A->B#1".
{ type: 'edge', from: 'A', to: 'B', key: 'A->B#1', state: 'active', ms: 300 }

// Wait step
{ type: 'wait', ms: 1000 }

// Reset step
{ type: 'reset', keepVisited: true }

Type Definitions

Full TypeScript definitions are available when installing via npm:

import type {
  FlowPlayer,
  FlowPlayerOptions,
  Step,
  Scenario,
  State,
  GraphIndex,
  DiagramGraph,
  DiagramKind,
  AnimatedSvgOptions,
  FlowPlayerError,
  EasingFunction,
  EasingConfig,
} from 'mermaid-flow-player';