Mermaid Core is the JavaScript rendering engine that powers Mermaid diagrams in the browser and server-side environments. It parses Mermaid markup, builds an internal scene graph, and renders vector output to SVG or Canvas. This overview explains core components, supported diagram types, integration options, configuration behavior, and practical considerations for developers using Mermaid Core in web and tooling projects.
What Is Mermaid Core
Mermaid Core is the runtime responsible for converting Mermaid text descriptions into interactive, accessible diagrams. It handles parsing, layout computation, and rendering, enabling consistent output across web and Node contexts. As the foundation for Mermaid Live Editor, documentation tools, CI checks, and automated diagram generation, Core balances performance with extensibility while supporting configuration for themes, flows, and security policies.
Supported Diagram Types
Mermaid Core includes layout engines for multiple diagram domains, each with its own grammar and layout rules. Commonly used diagram types are listed below with their primary layout direction and typical use cases.
| Diagram Type | Primary Direction | Common Use Cases |
|---|---|---|
| flowchart | TB / LR / RL | Process flow, decision logic |
| sequence | top-down | Message ordering, interactions |
| state | top-down | State transitions |
| gantt | horizontal time | Project schedules |
| er | auto | Data model relationships |
| class | top-down | OO structure |
| graph | TB / LR / RL | Networks, custom relations |
Rendering Paths
Mermaid Core can render to SVG or Canvas, with configuration that influences performance and output quality. SVG rendering is default for most targets because it produces crisp vectors, supports CSS styling, and enables interaction and animation. Canvas rendering can improve perceived speed for very large diagrams, though it trades off native accessibility and zoom behavior. Server-side rendering in Node uses the same layout engines and outputs SVG strings for inclusion in documentation or CI reports.
SVG Rendering
Each diagram element becomes a distinct SVG node, enabling tooltips, CSS theming, and external script hooks. Accessibility attributes such as titles and descriptions are injected when enabled, and styles can be controlled via classes and variables.
Canvas Rendering
Canvas outputs raster content and is generally used when diagram complexity causes layout bottlenecks. Interaction is limited to the drawing surface, and additional overlays are required for features like zoom and pan.
Integration Approaches
Developers can include Mermaid Core via CDN, package managers, or bundler plugins. The exported function accepts a container element or selector and a configuration object, returning a promise that resolves when layout and rendering complete. Build-tool integrations allow diagrams to be prerendered at build time, reducing runtime cost and ensuring static output consistency.
- CDN: load mermaid.min.js and call mermaid.render on DOMContentLoaded.
- npm: install mermaid and import the core entry for custom pipelines.
- SSR: use mermaid.render to produce SVG strings during server-side generation.
- CLI: the mermaid CLI wraps Core to generate PNG or SVG files from text files.
Configuration and Runtime Options
Mermaid Core accepts configuration for theme, startOnLoad, security restrictions, and flow direction. Theme presets influence colors and typography, while security settings control whether external content is allowed. Programmatic configuration can be supplied at render time or applied globally to affect all diagrams on a page.
| Option | Purpose | Typical Values |
|---|---|---|
| theme | Color and styling preset | default, dark, neutral |
| startOnLoad | Auto-render diagrams | boolean |
| securityLevel | Restrict external resources | strict,loose |
| flowDirection | Default layout direction | TB, LR, RL |
| maxTextSize | Font-size cap for layout | number in px |
Extensibility and Plugins
Mermaid Core supports plugins for custom elements, additional arrow markers, and diagram type extensions. Plugin registration occurs before rendering and can be scoped to specific diagram instances. Because plugin execution happens inside the Core runtime, compatibility and performance impact should be evaluated per project.
Performance Considerations
Diagram complexity, node count, and browser capabilities affect rendering time. For large flowcharts or sequence diagrams, consider simplifying markup, using subgraphs, or switching rendering mode based on measured outcomes. Profiling layout duration and SVG node count can guide decisions between SVG and Canvas paths.
Accessibility and Internationalization
When SVG rendering is used, Mermaid Core adds title and desc elements to provide accessible names. Text content is preserved in source order, and bidirectional text is handled by the browser layout. Developers can supply custom titles and descriptions to improve clarity in screen readers and documentation contexts.
Versioning and Stability
Mermaid Core follows semantic versioning for its public APIs, including the render function and configuration schema. Layout engine changes may affect diagram appearance across major versions, so pinning a version is recommended for long-lived documentation assets. Migration guides are published with each major release to assist upgrades.
Troubleshooting Common Issues
Common issues include parse errors from unsupported syntax, theme mismatches, and security blocks on external content. Inspecting the browser console, validating diagram syntax, and checking configuration consistency usually resolve these. When using SSR, ensure the same Mermaid Core version on server and client to avoid mismatched SVG output.
Conclusion
Mermaid Core provides a robust, evergreen foundation for diagram creation in documentation, tooling, and web applications. By understanding its rendering options, configuration model, and integration patterns, teams can produce consistent, accessible diagrams that scale with project needs.