Alluvial diagram

Usage guidelines

Use an alluvial diagram when you want to show how the same data moves across several categorical dimensions. In other words, it shows how proportions of the same quantity change between various characteristics. For example: the same number of people could be broken down by different dimensions, like pet preference, age, country of origin, et cetera. The changes between dimensions could also happen over time.

An alluvial diagram can help to highlight patterns and trends that might not be immediately obvious from raw data. This diagram also makes it easier to understand how different factors are influencing the overall outcome.

Use alluvial diagrams for visualizing the flow of data or information between different categories or stages.

Label each category or stage clearly and consistently.

Don't overcomplicate your diagram with too many categories or stages. Don't use more than five stages, and don't use more than five options per stage.

Spacing and positioning

Use 16px for the thickness of the node, and use 8px for the distance between the node and its label. Center-align labels to the node it belongs to. If a node value is very small, keep its height to a minimum of 2px. Use 16px between each node when the node height is bigger than its label. Otherwise, make sure there is 8px distance between text labels of the closest nodes.

By default, we place all labels to the right of their nodes, except for the ones of the first category. This way, the diagram is easier to read. However, you may place them all on the right if that works better for your use case.

Link curve

For very complex alluvial diagrams, the default way of linking nodes causes them to overlap. We solve this by changing the way links are formed, in particular how they are curved. This solution reduces clutter, and brings clarity when interpreting an alluvial diagram with many nodes.

Node labels order

By default, the labels are positioned in the following order: the name of the stage is first, its corresponding value is second. This way, when end users are reading the diagram for the first time, they start by scanning the name to get the context of the stage. Only after do they look at its corresponding value.

We offer the option to switch the order of node labels. In this case, the value is shown first, and the corresponding stage second. We advice to do this for scenarios when end users are viewing the alluvial diagram on a regular basis. In this case, we assume that they're familiar with the categories, so it makes sense to emphasize the number by displaying it first.

Color

Color should be used with purpose. If your main message is to show the different proportions at different stages, just use one color throughout the alluvial diagram. If your main message is to highlight a specific flow or category, use a different color to draw attention to it. If the meaning behind a category has a negative or positive connotation, and you want to highlight that, then consider using a "storytelling" color. This could be green, orange, or red. For color details, see our page on colors.

Link color

To tell a better story with colors, we recommend using a gradient for the links. This way, the color emphasizes the change of a state, and is connected visually to the beginning and the end of the respective nodes.

Node color

The "one node, one color rule" is the default way of visualizing one stage in a flow. However, in some scenarios there could be an exception. In that case, we recommend combining colors into one node, which resembles a stacked bar chart. Only do this for nodes that are either in the beginning or at the end of the diagram.

Behavior

Hover behavior

When hovering over a node, the closest neighbor nodes are highlighted. When hovering over a link, the two nodes around it are highlighted. The numbers corresponding to the highlighted nodes are also updated accordingly to the highlighted relations. See some examples in the images below.

It's possible to highlight the full flow of the node or link that's being hovered. In that case, it's essential to supply the diagram with extra data, so all possible relationship combinations are calculated.

No data behavior

For an alluvial diagram, it's critical that there are no missing data points. If one or more data points are missing from the data set, then they aren't calculated in the total. This can result in a misleading diagram. Because of that, we advice against n/a data fields. If you can't avoid missing data, then you can manually add an extra node for the unidentified/undefined category.

Zero value behavior

Typically, if a value is zero it's not shown. However, if your use case requires the explicit display of a zero value, then we recommend using a height of 2px and making the color gray.

Alluvial diagram shows you the flow of aggregated units from one group to the next.

Usage

Importing

import { LumeAlluvialDiagram } from '@adyen/lume';

Basic use

To generate a simple alluvial diagram with default settings, simply pass the data and labels props.

<template>
  <lume-alluvial-diagram
    :data="data"
    :labels="labels"
  />
</template>

<script
  lang="ts"
  setup
>
  import { ref } from 'vue';

  const data = ref([
    {
      values: [
        {
          label: 'A',
          color: 'skyblue',
          value: 'A',
          targets: [
            { node: 'D', value: 15 },
            { node: 'E', value: 42 },
            { node: 'G', value: 1 },
          ],
        },
        {
          label: 'B',
          color: 'royalblue',
          value: 'B',
          targets: [
            { node: 'D', value: 45 },
            { node: 'E', value: 42 },
          ],
        },
        {
          label: 'C',
          color: 'violet',
          value: 'C',
          targets: [{ node: 'D', value: 20 }],
        },
        {
          label: 'D',
          value: 'D',
          color: 'darkteal',
        },
        {
          label: 'E',
          value: 'E',
          color: 'gold',
        },
        { label: 'G', value: 'G', color: 'skyblue' },
      ],
      nodePadding: 20,
      nodeWidth: 16,
    },
  ]);

  const labels = ref(['Jan', 'Feb', 'Mar', 'Apr', 'May']);
</script>

API

Props

Alluvial dataset

The data provided to an Alluvial should be a single item array, and the values should be the alluvial nodes, and have a targets array, e.g.:

[
  {
    values: [
      {
        label: 'Dogs',
        color: 'skyblue',
        value: 'dogs', // value is treated as the node ID
        targets: [
          { node: 'Lisbon shelter', value: 15 },
          { node: 'Porto shelter', value: 42 },
        ],
      } as AlluvialNode,
    ],
  },
];

Interface: AlluvialNode

Interface: AlluvialNodeTarget

Alluvial options

Interface: AlluvialDiagramOptions

Highlighted elements

In the alluvial diagram, there are multiple possible behaviors for when you hover a node or a link. Lume provides two different behaviors, plus a way to add your own custom one.

full

When a node or link is hovered, highlight the full connecting nodes/links. This is the default behavior.

closest

When a node or link is hovered, highlight only the closest nodes/links.

Custom function

You can customize which nodes/links to highlight upon hovering by passing a GetHighlightedElementsFunction function in the highlightedElements option.

This function has two arguments: the node/link being hovered and a graph representing the sankey layout.
It must return an object with a nodes map of node IDs and the value they should display, and a links array of link IDs. These are the nodes/links that will be highlighted when hovered.

type GetHighlightedElementsFunction = (
  element:
    | SankeyNode<SankeyNodeProps, SankeyLinkProps>
    | SankeyLink<SankeyNodeProps, SankeyLinkProps>,
  graph: SankeyGraph<SankeyNodeProps, SankeyLinkProps>
) => HighlightedElements;

interface HighlightedElements {
  nodes: { [id: string]: string | number };
  links: Array<string>;
}

Note: Link IDs follow this structure: {SOURCE_NODE_ID} + ':' + {TARGET_NODE_ID}

Slot props

node-text-{NODE_ID}

Available for every node in the diagram. NODE_ID is the value provided in the dataset.