Mermaid Review

Mermaid is a JavaScript library (version 12.1.0) that turns text definitions into diagrams. The docs list flowchart, sequence, use case, Gantt, class, Git graph, entity relationship (marked experimental), user journey, quadrant chart, and XY chart as featured types, and also state, swimlanes, requirement, C4 (with a caution), mindmaps, timeline, ZenUML, Sankey, block, packet, Kanban, architecture, radar, event modeling, treemap, Venn, Ishikawa, Wardley, Cynefin, TreeView, and pie. You embed it with a CDN script or ES module (elements with the mermaid class are rendered to SVG) or install it with npm, yarn, or pnpm, which requires Node.js 22.12.0 or later. Configuration is through mermaid.initialize, mermaid.run is the preferred way to render (mermaid.init is deprecated, and rendering starts on page load unless startOnLoad is false), and v12.0.0 bundles the ELK layout engine and uses it by default, with the tiny build falling back to Dagre unless you register the layout-elk package. The Mermaid Live Editor lets non-programmers experiment, and OpenAlternative notes native rendering in GitHub, Notion, and Confluence.

Load it from a CDN such as jsDelivr with mermaid.initialize, or npm i mermaid in a project. The docs warn that sanitizing user-supplied diagram code is hard to guarantee completely, and the securityLevel setting controls the trade-off: strict (the default) encodes HTML in labels and disables click functionality, antiscript allows HTML but removes script elements and enables clicks, loose allows HTML and clicks and puts the trust decision on the site owner, and sandbox renders inside a sandboxed iframe that blocks JavaScript, which can break interactive features such as scripts, popups, and links. Default fonts depend on the diagram type and theme, and the docs recommend web fonts for consistent rendering. The pages we read do not document maximum diagram size limits, so check the configuration schema if you render very large diagrams.

You write something like a few lines of flowchart syntax, and the library lays out the nodes automatically. This is fast for documentation and architecture notes, but you have limited control over exact positioning compared with a drag-and-drop tool, and the layout engine choice (Dagre or ELK) changes how dense diagrams look. This section reflects the docs and repository; we did not test large diagrams.

• Text-to-diagram syntax that stays in version control
• 30+ diagram types including flowchart, sequence, Gantt, class, ER, state, Kanban, and architecture
• Renders to SVG in the browser, with CDN and npm distribution
• ELK and Dagre layout engines
• Four security levels, including a sandboxed iframe mode
• Mermaid Live Editor for quick editing and sharing
• Native rendering in many Markdown and documentation tools

• Diagrams live next to code and can be reviewed in pull requests
• Very widely supported, with about 91,000 stars and a large ecosystem
• Many diagram types from a single syntax family
• MIT license and a simple embedding story

• Automatic layout means you cannot position nodes precisely, and complex diagrams can get messy
• Some diagram types are experimental, and C4 is flagged with a caution
• Sanitizing untrusted diagram input is not guaranteed, and the sandbox security level disables interactivity such as links and scripts
• Needs Node.js 22.12.0 or later for npm usage, and deprecated APIs such as mermaid.init will be removed
• Collaboration features sit in the paid Mermaid Chart product, where co-editing and external sharing start at the Premium plan

The Mermaid library is free and open source under the MIT license. Mermaid Chart plans are Basic (free, with a small number of diagrams and 15 AI credits), Plus at $10 per user per month billed annually (unlimited diagrams and 300 AI credits per year), Premium at $20 per user per month billed annually (2,000 AI credits per year, unlimited free viewer seats, unlimited teams and projects, and co-editing and external sharing), and Enterprise (custom, with SSO, custom contracts, IP management, and a customer success manager).

Visio and Lucidchart are graphical diagram editors with templates, shape libraries, and enterprise features. Mermaid takes the opposite approach: you describe the diagram in text and let the library draw it, which suits developers and technical writers who want version control and automation. If you need pixel-perfect layouts or non-technical collaborators drawing freehand, a graphical tool or Excalidraw is a better fit, and Mermaid Chart exists for teams that want hosted editing with Mermaid syntax.

• Developers and technical writers who document architecture in Markdown
• Teams that want diagrams reviewed in pull requests
• Documentation sites that generate diagrams from data

• Designers who need exact layouts and styling control
• Non-technical users who prefer drag and drop
• Very large or dense diagrams where automatic layout struggles