Mermaid conversion API

This reference covers the public Mermaid conversion path supplied by @excalidraw/mermaid-to-excalidraw and @excalidraw/excalidraw. The evidenced Excalidraw dependency is version 2.2.2; verify the installed version before relying on version-sensitive behavior.

Conversion pipeline

The API has two required stages: parse Mermaid text into skeleton elements and files, then convert the skeletons into fully qualified Excalidraw elements.

const { elements, files } = await parseMermaidToExcalidraw(source, options);
const fullElements = convertToExcalidrawElements(elements);

parseMermaidToExcalidraw

parseMermaidToExcalidraw(
  mermaidSyntax: string,
  options?: { fontSize?: number },
): Promise<{ elements: ExcalidrawElementSkeleton[]; files: Record<string, unknown> }>

Parses the Mermaid definition and returns skeleton elements. The documented option is fontSize. The result is asynchronous.

const result = await parseMermaidToExcalidraw(
  "flowchart LR\n  A[Start] --> B[Finish]",
  { fontSize: 18 },
);

The parser rejects invalid Mermaid input. Catch the rejection and preserve the source so the caller can correct it.

convertToExcalidrawElements

convertToExcalidrawElements(
  elements: ExcalidrawElementSkeleton[],
): ExcalidrawElement[]

Converts skeletons into fully qualified elements. Call it before rendering or inserting the result into an Excalidraw scene. Import it from @excalidraw/excalidraw.

Supported flowcharts

Flowcharts are the supported editable diagram type. Rectangles, circles, diamonds, arrows, and subgraphs are represented in Excalidraw.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C((Done))

Fallbacks

Subroutine, cylindrical, asymmetric, hexagon, parallelogram, and trapezoid shapes fall back to rectangles. Mermaid Markdown strings fall back to regular text. Basic FontAwesome icons are not rendered. Cross arrowheads fall back to bar arrowheads.

Diagram types other than flowcharts are rendered as an image rather than converted into editable shape elements. Treat that as a different output contract and handle the returned files accordingly.

Errors and recovery

For the implementation model, read Mermaid parser architecture. For a complete example, follow Convert Mermaid to Excalidraw.