How to Use the Mermaid JavaScript Library to Create Flowcharts
If you’ve recently searched for an online diagramming tool, you might have noticed that most of them rely on drag-and-drop functionality. While this is helpful for people who can’t code, it can be hard to maintain. It can also be a bit difficult to m...
If you’ve recently searched for an online diagramming tool, you might have noticed that most of them rely on drag-and-drop functionality. While this is helpful for people who can’t code, it can be hard to maintain. It can also be a bit difficult to manipulate, having to move all those shapes into an editor, and it’s not as intuitive when trying to arrange lines and boxes so they don’t overlap.
Luckily, there are solutions that have taken a different path. They are based on libraries that can organize the shapes and lines for you. What you have to do instead is provide a script designed specifically for that tool outlining what kind of shapes you want to see and their relationships.
In this article, we’ll talk about a popular script-based diagramming tool called Mermaid. You’ll learn how Mermaid works and how you can use it to create flowcharts. We’ll also cover how to style your flowcharts in Mermaid. By the end, you should be able to use this helpful tool to create your own flowcharts.
Table of Contents
What is Mermaid?
Mermaid is a JavaScript library that translates written declarations of entities and relationships into diagrams. It’s like coding a diagram. The instructions are also Markdown-compliant.
Mermaid is not the only tool of this kind. There are other ones, like PlantUML, that have been around longer. But scripting with Mermaid has a very gentle learning curve, and it distinguishes itself from similar tools in many ways:
As opposed to other tools like PlantUML, Mermaid is made for the web. It is Node-compatible, and the diagrams show as modified SVGs with inserted “foreign objects”. These are more compliant with HTML and CSS frameworks.
Also compared to other scripting libraries, the resulting charts are more visually appealing, as they use advanced algorithms to place the shapes and arrows.
Mermaid also makes strong use of Markdown for labelling, and has more recently started using JavaScript object-like formatting for shape declaration.
It also has a strong support, is actively maintained, and makes use of well-known, robust JS graphics libraries like d3.js, cytospace.js, and dagre-d3.
When compared to the most common drag-and-drop types of diagramming tools, Mermaid has the same advantages as other script-based diagramming tools. With a script, we can talk about version control, reusability, and many other terms associated with programming and automation that might not be possible with drag-and-drop tools.
Challenges with Mermaid
Of course, it is not a perfect tool. One of the main challenges with Mermaid – and with many script-based diagramming tools – is that it’s a WYSIWYG tool: Mermaid’s results are almost impossible to predict, and after that they are hard to customize.
Also, for each diagram you can make with Mermaid, there are prescribed shapes and arrows – the introduction of new shapes or relationships are limited.
Some other limitations are:
As with other script-based tools, the script is not easy to debug, and for large diagrams the script can get very messy.
Even if the syntax is usually very intuitive, you have to learn a different syntax for each type of diagram.
Specifically for Mermaid, if you want to post-process the resulting diagram, you must find appropriate tools that can read the modified Mermaid SVGs.
But if you use Mermaid for the cases where it performs well, you will have an excellent tool at your service.
Mermaid allows you to create about 21 types of diagrams, each with its own syntactic rules. In this tutorial, we’ll take a closer look at the flowchart syntax, which I’ve been working with recently. This guide is for those comfortable with scripting, looking to build flowcharts, and seeking a quick reference to Mermaid syntax before diving deeper into the full documentation.
To keep this content focused on Mermaid syntax, I will avoid going into details about using JavaScript in combination with Mermaid and will instead refer to the relevant Mermaid documentation where applicable.
I’ll also highlight a few minor issues I’ve noticed while using the latest version of the tool (version 11) to help you avoid potential pitfalls.
Finally, if you need more guidance on creating flowcharts in general, I’ve created a separate post that walks you through the process step-by-step. While the examples in that post use Mermaid, its use is entirely optional.
Getting Started with Mermaid
You can use Mermaid in several different ways.
For those comfortable with web technologies, you can install Mermaid as a package or plugin and integrate it into applications using the Mermaid API, CLI, or plugins.
Once installed, you can render Mermaid diagrams wherever Mermaid syntax is included in your HTML or markdown files. The official documentation provides an example of rendering diagrams using a CDN (ESM style):
<html>
<body>
Here is one mermaid diagram:
<pre class="mermaid">
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
pre>
And here is another:
<pre class="mermaid">
graph TD
A[Client] -->|tcp_123| B
B(Load Balancer)
B -->|tcp_456| C[Server1]
B -->|tcp_456| D[Server2]
pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
script>
body>
html>
If you're using GitHub, Mermaid is supported in GitHub markdown. Additionally, Zaira Hira has written a helpful guide for Visual Studio Code users. Check your IDE for available plugins and extensions.
