@excalidraw/mermaid-to-excalidraw (3.0.0)

2026-10-28T14:49:15Z

Setup this registry in your project .npmrc file:

@excalidraw:registry=

To install the package using npm, run the following command:

npm install @excalidraw/mermaid-to-excalidraw@3.0.0

or add it to the package.json file:

"@excalidraw/mermaid-to-excalidraw": "3.0.0"

For more information on the npm registry, see the documentation.

mermaid-to-excalidraw

Convert mermaid diagrams to excalidraw

Diagrams are parsed and laid out by Pele, which reads Mermaid syntax and lays diagrams out without rendering them in the DOM (since v3; v2 used Mermaid itself, see Upgrading from v2).

Set up

Install packages:

yarn

Start development playground:

yarn start

Build command:

yarn build

Get started

parseMermaidToExcalidraw(diagramDefinition: string, config?: MermaidConfig)

The diagramDefinition is the mermaid diagram definition, and config is the mermaid config. mermaid-to-excalidraw only supports the 👇 config params

{
  /**
   * The flowchart curve style.
   * @default "linear"
   */
  flowchart?: {
    curve?: "linear" | "basis";
  };
  /**
   * Theme variables
   * @default { fontSize: "20px" }
   */
  themeVariables?: {
    fontSize?: string;
  };
  /**
   * Maximum number of edges to be rendered.
   * @default 500
   */
  maxEdges?: number;
  /**
   * Maximum number of characters to be rendered.
   * @default 50000
   */
  maxTextSize?: number;
}

Flowcharts (including swimlane-beta diagrams), sequence, class, ER and state diagrams are converted to Excalidraw elements. Other diagram types Pele supports are inserted as an image.

It needs DOM APIs (e.g. DOMParser, so a browser, or jsdom), but nothing is rendered into the document.

Example code:

import { parseMermaidToExcalidraw } from "@excalidraw/mermaid-to-excalidraw";

try {
  const { elements, files } = await parseMermaidToExcalidraw(
    diagramDefinition,
    {
      themeVariables: {
        fontSize: "25px",
      },
    }
  );
  // Render elements and files on Excalidraw
} catch (e) {
  // Parse error, displaying error message to users
}

Playground

Try out here.

Development

yarn test:visual to run visual tests
yarn test:visual:update to update visual tests
yarn test:visual:dev to run visual test dev server (usually better to use this over the playground)

Upgrading from v2

Diagrams are laid out by Pele instead of Mermaid, so they look different (e.g. node sizes and spacing, edge routes), and Mermaid is no longer a dependency. parseMermaidToExcalidraw is the same otherwise.
The engine and startOnLoad config params are gone.
Diagrams that Mermaid parsed but Pele doesn't now throw a parse error (Pele's errors follow Mermaid's format).
Known gap: <br> and \n in class members are drawn as is (Pele lays members out on one line).

v2 is maintained on the release/2.x branch.

API

Head over to the docs.

Support new Diagram type

Head over to the docs.

Dependencies

ID	Version
@excalidraw/markdown-to-text	0.1.2
nanoid	4.0.2
pele	1.8.0

Development Dependencies

ID	Version
@babel/core	7.12.0
@excalidraw/eslint-config	1.0.3
@excalidraw/excalidraw	^0.18.0-a9ca16e
@playwright/test	^1.58.2
@types/node	^20
@types/react	18.2.14
@types/react-dom	18.2.4
@typescript-eslint/eslint-plugin	5.59.9
@typescript-eslint/parser	5.59.9
@vitejs/plugin-react-swc	3.6.0
@vitest/coverage-v8	^1.6.0
cross-env	7.0.3
eslint	8.42.0
eslint-config-prettier	8.8.0
eslint-plugin-prettier	4.2.1
jsdom	^24.0.0
prettier	2.8.8
process	0.11.10
react	18.2.0
react-dom	18.2.0
rimraf	5.0.5
sass	1.74.1
typescript	5.2.2
vite	5.2.8
vitest	^1.6.0

Details

npm

2026-10-28 14:49:15 +00:00

3

MIT

latest

78 KiB

Assets (1)

mermaid-to-excalidraw-3.0.0.tgz 78 KiB

Versions (1) View all

3.0.0

2026-10-28