Getting started

InstallationCopy Anchor Link

The package converts definitions into Excalidraw element skeletons. You also need @excalidraw/excalidraw to turn them into elements and render them.

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

yarn add @excalidraw/mermaid-to-excalidraw @excalidraw/excalidraw

pnpm add @excalidraw/mermaid-to-excalidraw @excalidraw/excalidraw

Convert a diagramCopy Anchor Link

Converting takes two steps:

1. parseMermaidToExcalidraw parses and lays out the definition, and resolves to element skeletons (and files, for diagrams inserted as an image).
2. convertToExcalidrawElements turns the skeletons into full Excalidraw elements.

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

const definition = `flowchart LR
  A[Write the definition] --> B{Valid?}
  B -->|yes| C[Excalidraw elements]
  B -->|no| D[Parse error]`;

try {
  const { elements, files } = await parseMermaidToExcalidraw(definition);

  excalidrawAPI.updateScene({
    elements: convertToExcalidrawElements(elements),
  });
  if (files) {
    excalidrawAPI.addFiles(Object.values(files));
  }
  excalidrawAPI.scrollToContent(excalidrawAPI.getSceneElements(), {
    fitToContent: true,
  });
} catch (error) {
  // Not valid Mermaid syntax: show the error to the user
}

excalidrawAPI is the imperative API of your <Excalidraw /> component.

Adding to an existing sceneCopy Anchor Link

The example above replaces the scene. To insert a diagram next to what's already on the canvas, append the converted elements to excalidrawAPI.getSceneElements() instead. If the same diagram can be inserted more than once, pass regenerateIds: true so each copy gets its own element ids:

const newElements = convertToExcalidrawElements(elements, {
  regenerateIds: true,
});

excalidrawAPI.updateScene({
  elements: [...excalidrawAPI.getSceneElements(), ...newElements],
});

Things to knowCopy Anchor Link

• It needs DOM APIs. The conversion reads the SVG Pele draws with DOMParser, so run it in a browser (or with jsdom). Nothing is rendered into the page.
• Load Excalidraw's fonts first. Labels are measured with Excalifont, the font Excalidraw draws them with, so that shapes fit their text. If Excalifont isn't loaded yet when you convert, a fallback font is measured instead and labels may not fit their shapes exactly.
• Code is loaded per diagram type. Since v3.1, the code for each diagram type loads the first time you convert a diagram of that type. Bundlers emit it as separate chunks, so a first flowchart downloads about 66 KiB (brotli) instead of every diagram type up front.
• Invalid definitions throw. Parse errors follow Mermaid's error format, so you can show them to users as is.

PlaygroundCopy Anchor Link

The playground converts any definition you type and shows Pele's drawing next to the Excalidraw result.