DEV Community

Cover image for How to Make Flowcharts with Mermaid.js
Matt Eland
Matt Eland

Posted on • Originally published at newdevsguide.com

How to Make Flowcharts with Mermaid.js

Mermaid.js is a powerful JavaScript library that can build a variety of charts and diagrams from a specialized flavor of markdown. While Mermaid.js supports many common and uncommon types of charts, perhaps the most frequently used type of chart it supports is the lowly flowchart.

Flowcharts are simple and flexible charts that connect different shapes together with arrows to convey a visual picture.

Process FlowchartFlowcharts are often used to illustrate logical flows or decision-making processes and are frequently used in software engineering to show data or communication flows in software systems.

To show you what Mermaid.js can do with flowcharts, let's take a look at building out a simple flowchart illustrating a REST request that flows from the client to the server, is fulfilled by the database, and then returns back to the client.

Basic Flowcharts with Mermaid.js

We'll start first by creating a flowchart in markdown and defining the three shapes we'll want on our flowchart.

The markdown for this looks as follows:

flowchart
    Client
    Server
    Database
Enter fullscreen mode Exit fullscreen mode

When rendered in a markdown viewer that supports Mermaid.js, this markdown displays the following diagram:

Flowchart with 3 shapes without relationships

There are a growing number of places that support Mermaid.js diagrams including GitHub markdown, Polyglot Notebooks, and the Mermaid.js live editor. You can also import Mermaid.js to transform markdown on your webpage into diagrams.

Relationships in Mermaid.js

Because a flowchart without any relationship lines is fairly useless, let's see how Mermaid.js allows us to define relationships.

With Mermaid.js you simply define a relationship in markdown with --> between the two connected shapes and the diagram takes care of the rest.

Here's our flowchart with a pair of relationships:

flowchart
    Client --> Server
    Server --> Database
Enter fullscreen mode Exit fullscreen mode

Flowchart with Relationships

This is getting there, but most client / server communication diagrams are arranged from left to right. Mermaid.js lets us make that tweak by stating flowchart LR:

flowchart LR
    Client --> Server
    Server --> Database
Enter fullscreen mode Exit fullscreen mode

Great! Now we have the communications from the client to the server and from the server to the database, but it'd be nice to represent the responses as well.

With Mermaid.js you can have multiple connections to each shape if it makes sense. Additionally, Mermaid.js has a variety of connector styles, including -.-> to represent a dotted arrow instead of a solid arrow.

flowchart LR
    Client --> Server
    Server --> Database
    Database -.-> Server
    Server -.-> Client
Enter fullscreen mode Exit fullscreen mode

Flowchart with multiple relationshipsNow the communications are a lot more explicit, but it'd be nice to label the contents of each message.

Note: if your primary focus is communications between systems, you may want to check out using Mermaid.js for sequence diagrams. Alternatively, if your focus is the data, you should investigate entity relationship diagrams.

Mermaid.js allows you to provide text over each relationship line if you'd like by typing the text in the middle of the connector arrow.

Additionally, because Mermaid.js is very sensitive to inconsistent spelling, you may want to define your shapes at the beginning of a flowchart and give them an alias to reduce typing in your markdown.

The code below aliases the client as c, the server as s and the database as db. Additionally, each relationship is now given text to illustrate what flows between systems.

flowchart LR
    c[Client]
    s[Server]
    db[Database]

    c -- HTTP GET --> s
    s -- SQL Query --> db
    db -. Result Set .-> s
    s -. JSON .-> c
Enter fullscreen mode Exit fullscreen mode

FlowchartThis diagram is now significantly more helpful and if we wanted to rename a shape, we only need to rename it in the line that defines the shape initially.

Customizing Mermaid.js Flowcharts

Additional Connector Types

Mermaid.js supports more than just solid and dashed arrows.

Below are a variety of connector types that Mermaid.js currently supports. Additionally, I have a line that shows you how you can define multiple relationships in a single line via chaining:

flowchart LR
    Base --> Arrow
    Base ==> Heavy
    Base -.-> Dotted
    Base --- Line
    Base --> You --> Can --> Chain --> Relations --> On --> One --- Line
Enter fullscreen mode Exit fullscreen mode

Flowchart ConnectorsNote: Line is mentioned twice on the last two lines of the markdown which explains why there are two lines going to it.

Customizing Flowchart Shapes

Our client / server communication diagram looks pretty good, but most programmers I've worked with draw their databases as drums on diagrams.

Mermaid.js allows you to customize shapes if you'd like and helpfully includes a database shape via [(Name)] syntax.

The code below customizes the shape of the database element on its definition line:

flowchart LR
    c[Client]
    s[Server]
    db[(Database)]

    c -- HTTP GET --> s
    s -- SQL Query --> db
    db -. Result Set .-> s
    s -. JSON .-> c
Enter fullscreen mode Exit fullscreen mode

Flowchart ShapesAs you might expect from a flowchart library, Mermaid.js offers a large number of custom shapes including these below:

flowchart
    a[Default]
    b([Rounded])
    c[(Database)]
    d[[Subroutine]]
    e((Circle))
    f>Note]
    g{Decision}
    h{{Hexagon}}
    i[/Parallelogram/]
    j(((Double Circle)))
Enter fullscreen mode Exit fullscreen mode

Flowchart Shapes

For a more complete list of shapes, I recommend you view the Mermaid.js flowchart documentation.

Managing Complexity with Subgraphs

While we already have a perfectly usable diagram, we could refine it further by illustrating where each part of our application is hosted.

In Mermaid.js you can add sections or groups to your flowcharts to visually group related elements.

Mermaid.js calls these groupings of elements "subgraphs" and allows you to define them by stating subgraph Graph Name to start the group and end to end it.

Here's our graph that illustrates that the client is hosted on Netlify and the server and database are running on Azure:

flowchart LR
    subgraph Azure
        s[Server]
        db[(Database)]
    end
    subgraph Netlify
        c[Client]
    end

    c -- HTTP GET --> s
    s -. JSON .-> c    
    db -. Result Set .-> s
    s -- SQL Query --> db
Enter fullscreen mode Exit fullscreen mode

Flowchart with Groupings

The diagram above makes this look easy, but I had to try a number of different ordering approaches until I got Mermaid.js to organize the groups the way I wanted to.

Once you use subgraphs, you will likely need to do some additional tweaks to help your diagram layout meet your needs.

Adding Icons with Font Awesome

Like Mermaid.js mind maps, flowcharts can use icons to improve their readability or visual appeal.

If you or the tool you are using have already imported Font Awesome, you can specify an icon for each shape via the fa: prefix and then the name of your icon as shown below:

flowchart LR
    subgraph Azure
        s[fa:fa-code Server]
        db[(fa:fa-table Database)]
    end
    subgraph Netlify
        c[fa:fa-user Client]
    end

    subgraph Netlify
    end
    subgraph Azure
        direction LR
    end

    c -- HTTP GET --> s
    s -- SQL Query --> db
    db -. Result Set .-> s
    s -. JSON .-> c
Enter fullscreen mode Exit fullscreen mode

Flowchart with Icons

While I don't view these icons as particularly helpful in the above example, I certainly could see other diagramming cases that could benefit from adding iconography.

Closing Thoughts

Mermaid.js flowcharts are simple, functional, and efficient.

Beyond helping you generate visuals, one of the key advantages of Mermaid.js flowcharts is that they are easy to embed in markdown documents as raw markdown. This lets others see your diagrams and easily make additions or corrections as systems inevitably change.

Finally, since these diagrams are stored as markdown, they are trivially easy to store in a version control system.

I personally plan on using Mermaid.js flowcharts for quick high level system architecture diagrams going forward. They may not have the full visual polish that you might want for something in a formal presentation, but they are simple, accessible, and powerful.

Top comments (5)

Collapse
 
aarone4 profile image
Aaron Reese

The most fun I had with mermaid was taking a workflow system (think Microsoft Flow but looking like windows 3.1). Each step, it's actions and description and next available steps was stored in a variable length field with lots of control characters. I had to write SQL to generate a data set that gave you the setup and links and output it to an SSRS report (you can't embed external js libraries in SSRS) so I then had a link on the report to mermaid where you could copy and paste the markup to get the flowchart.... Quite Health-Robinsonesque but it was an interesting coding excercise.

Collapse
 
integerman profile image
Matt Eland

I love this so much. Thank you for sharing!

Collapse
 
vulcanwm profile image
Medea

This is a really helpful post!

Collapse
 
integerman profile image
Matt Eland

Thank you! I'm really enjoying Mermaid.js

Collapse
 
vulcanwm profile image
Medea

it seems really interesting! might try it out soon