Sankey diagrams are a powerful tool for visualizing flow data. They’re often used for activities related to energy studies, resource allocation and cost analysis. The capability to create these diagrams has been significantly enhanced by a recent contribution to MermaidJS. Nikolay Rozhkov, a software engineer and active member of the Mermaid community, has added the functionality for Sankey diagrams into the platform.

In this post, we will explore the basics of Sankey diagrams, discuss the advantages of using MermaidJS as your Sankey diagram maker, explore some Sankey diagram examples and guide you through the process of making your own using Mermaid.

What is a Sankey diagram? #

Sankey diagrams are specialized flow diagrams that visualize the distribution and transfer of resources, energy or information between multiple entities. The width of the arrows in the diagram is proportional to the flow quantity they represent, making it easier to understand the flow distribution at a glance.

These diagrams can be used for several purposes, including visualizing a supply chain management process, analyzing a marketing funnel or mapping out a user or customer journey.

Sankey diagrams are named after Matthew Henry Phineas Riall Sankey, an Irish engineer who popularized this type of diagram while showcasing the energy efficiency of a steam engine in the late 1800s.

Sankey Diagram Examples #

So what do these diagrams look like? How can you apply them to your field of work?

You could for instance, as shown in the following Sankey diagram example, visualize how a factory distributes its energy between the assembly line and maintenance. The assembly line then contributes to producing finished goods, as does maintenance, albeit to a lesser extent:

sankey-beta
  Factory, Assembly Line, 50
  Factory, Maintenance, 30
  Assembly Line, Parts, 10
  Assembly Line, Finished Goods, 40
  Maintenance, Finished Goods, 15
  Maintenance, Waste, 15

Another example is how money flows from a bank account, dividing it into expenses and savings. The expenses are further broken down into taxes and rent:

sankey-beta
  Bank, Expenses, 100
  Bank, Savings, 200
  Expenses, Taxes, 50
  Expenses, Rent, 50

The Mermaid syntax examples above demonstrate how straightforward it is to create Sankey diagrams for different use cases, and the accompanying explanations provide context for each example. Mermaid offers a text-based approach to diagramming, making it a convenient and fun choice for developers and data analysts. Let’s look a little closer at the syntax of Sankey diagrams in Mermaid.

Using Mermaid as Your Sankey Diagram Maker #

The syntax for Sankey diagrams in Mermaid is designed to be straightforward and closely resembles plain CSV format. Below is a summary of the syntax based on the official Mermaid documentation.

The basic idea is to start with the keyword “sankey-beta” followed by the raw CSV data. The CSV must contain three columns representing the source, target, and value, respectively. The diagram is new, which is why the diagram starts with sankey-beta. This is a disclaimer in case of initial use results in some parts of the grammar having to change. When the beta phase is done the sankey will be the starting text for the sankey diagrams, but sankey-beta will continue to work.

sankey-beta
  %% source,target,value
  Homepage,Product Page,400
  Homepage,Contact Us,100
  Product Page,Cart,150
  Product Page,Exit,50

Handling Commas and Quotes #

If you need to include a comma in your data, wrap it in double quotes. For double quotes within the data, use a pair of them inside the quoted string.

Configuration Options #

If you are integrating Mermaid into a site or an app, you can customize the diagram’s dimensions, link colors, and node alignments through Mermaid configuration.

const config = {
  startOnLoad: true,
  securityLevel: 'loose',
  sankey: {
    width: 800,
    height: 400,
    linkColor: 'source',
    nodeAlignment: 'left'
  }
};

mermaid.initialize(config);

This section provides a concise guide to creating Sankey diagrams using Mermaid, focusing on the syntax and configuration options.

Getting started with Mermaid Chart #

Sankey diagrams offer a compelling way to visualize flow data and Mermaid, together with Mermaid Chart makes the creation of these diagrams both efficient and straightforward. The contribution from Nikolay Rozhkov has added value to the platform, making it easier for users to leverage the power of Sankey diagrams for various applications.

Interested in building your own Sankey diagram from simple code? Try Mermaid Chart for free to discover your new Sankey diagram maker.