Convert Mermaid to Excalidraw
Install the Mermaid converter and turn a flowchart definition into editable Excalidraw elements.
In this tutorial, you will install @excalidraw/mermaid-to-excalidraw, convert a Mermaid flowchart, and prepare the result for an Excalidraw editor. Success means you have fully qualified elements and any associated files.
Before you begin
You need a JavaScript or TypeScript project with npm or Yarn, @excalidraw/excalidraw, and a host that can render the returned elements.
Keep the Mermaid definition available as a string in the same runtime as the converter. The documented editable path is for flowcharts; the parser returns skeleton data first, so the Excalidraw package must perform the second-stage conversion before you render the scene.
Convert a flowchart
npm install @excalidraw/mermaid-to-excalidraw @excalidraw/excalidrawyarn add @excalidraw/mermaid-to-excalidraw @excalidraw/excalidrawThe packages are available to import from your project.
Create a Mermaid string whose first statement starts with flowchart.
const diagramDefinition = `flowchart TD
Start[Start] --> Check{Ready?}
Check -->|Yes| Done[Done]
Check -->|No| Wait[Wait]`;The definition describes nodes and connections that can map to Excalidraw shapes and arrows.
Call parseMermaidToExcalidraw with the definition and an optional font size.
import { parseMermaidToExcalidraw } from "@excalidraw/mermaid-to-excalidraw";
const { elements, files } = await parseMermaidToExcalidraw(
diagramDefinition, { fontSize: 20 },
);The promise resolves with skeleton elements and a files collection.
Pass the skeleton elements to convertToExcalidrawElements.
import { convertToExcalidrawElements } from "@excalidraw/excalidraw";
const excalidrawElements = convertToExcalidrawElements(elements);The result is ready for the editor's scene-management flow. Retain files with the scene state.
Wrap parsing and conversion in try/catch and preserve the source.
try {
const { elements, files } = await parseMermaidToExcalidraw(diagramDefinition, { fontSize: 20 });
const excalidrawElements = convertToExcalidrawElements(elements);
// Render excalidrawElements and retain files.
} catch (error) {
console.error("Mermaid conversion failed", error);
}The caller can show the error and let the reader correct the Mermaid text.
The flow is source text, skeleton data, fully qualified elements, and editor rendering.
Verify the result
Confirm that the promise resolves, excalidrawElements is populated, and the scene contains editable nodes and arrows. Definitions beginning with flowchart, flowchart LR, or a recognized commented form pass the initial definition check.
Troubleshoot conversion
If parsing rejects the input, check that it starts with flowchart and uses valid Mermaid syntax. If a non-flowchart becomes an image, that is the documented fallback. If rendering fails after parsing, verify that you passed elements through convertToExcalidrawElements.
If the definition is prefixed with a recognized Mermaid comment, keep the comment directly before the flowchart declaration; the recognition check accepts that form as well. If the promise resolves but the result is not editable, inspect whether the renderer received the converted elements rather than the parser's skeletons, and retain the returned files collection with the scene state.
Next, consult the Mermaid conversion API or read the parser architecture.