How to Make Flowcharts with Mermaid.js
Tags: mermaid, markdown, beginners, flowcharts
Published: 2023-04-16 03:08:31

---
title: How to Make Flowcharts with Mermaid.js 
published: true
series: Mermaid.js
description: Mermaid.js lets you create flowcharts from simple markdown. This helps you create more compelling documentation and easily version diagrams.
tags: Mermaid, Markdown, Beginners, Flowcharts
canonical_url: https://newdevsguide.com/2023/04/15/mermaid-flowcharts/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m14b73a8qfjn3na2ek10.png
---

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 Flowchart](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-74.png?resize=794%2C169&ssl=1)Flowcharts 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
```

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

![Flowchart with 3 shapes without relationships](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-72.png?resize=318%2C53&ssl=1)

There are a growing number of places that support Mermaid.js diagrams including GitHub markdown, [Polyglot Notebooks](https://newdevsguide.com/2022/12/14/polyglot-notebooks-csharp/), and [the Mermaid.js live editor](https://mermaid.live). 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
```

![Flowchart with Relationships](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-71.png?resize=99%2C214&ssl=1)

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
```

![](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-70.png?resize=315%2C49&ssl=1)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
```
![Flowchart with multiple relationships](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-69.png?resize=315%2C50&ssl=1)Now 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](https://newdevsguide.com/2023/04/10/mermaid-sequence-diagrams/). Alternatively, if your focus is the data, you should investigate [entity relationship diagrams](https://newdevsguide.com/2023/04/08/creating-erds-with-mermaid/).*

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
```

![Flowchart](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-66.png?resize=463%2C71&ssl=1)This 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
```

![Flowchart Connectors](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-73.png?resize=782%2C318&ssl=1)*Note: `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
```


![Flowchart Shapes](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-65.png?resize=459%2C78&ssl=1)As 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)))
```


![Flowchart Shapes](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-64.png?resize=799%2C79&ssl=1)

For a more complete list of shapes, I recommend you view [the Mermaid.js flowchart documentation](https://mermaid.js.org/syntax/flowchart.html).

## 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
```


![Flowchart with Groupings](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-63.png?resize=559%2C151&ssl=1)

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](https://newdevsguide.com/2023/04/14/mermaid-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](https://fontawesome.com/), 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
```


![Flowchart with Icons](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-62.png?resize=629%2C162&ssl=1)

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.