---
title: "Alluvial"
description: "Multi-stage flow. What the alluvial is for, the data it needs and every option it has."
section: "Widgets"
canonical: "https://banksync.io/docs/widgets/chart-alluvial"
specs: ["dashboards"]
operationBindings: [{"capability":"dashboards","operation":"dashboards.author"}]
---

Multi-stage flow. It sits in the **Flow & network** group of the widget library.

![Example alluvial on a BankSync dashboard](https://cdn.banksync.io/screenshots/docs/charts/alluvial.62d6ebe357d7cfbd.png)

## When to use it

An Alluvial chart follows the same items through ordered stages, such as account, then category, then merchant. It answers "how does spending split at each step, and where do paths cross?". You pick two or more stage columns in order, and an optional amount sets the width.

## When to pick something else

- Just one hop from source to target? A **Sankey** is simpler.
- Want nested boxes instead of paths? Use a **Treemap** or **Sunburst**.
- Comparing the mix within each group? Use a **100% stacked bar**.

## The data it needs

Pick these in the **Data** tab of the inspector. BankSync suggests a column for each when your source has an obvious match.

| Field      | Needed | Pick       | Notes |
| ---------- | ------ | ---------- | ----- |
| **Source** | Yes    | a category |       |
| **Target** | Yes    | a category |       |
| **Value**  | Yes    | a number   |       |

Rows that share a category are combined before drawing: choose **Sum**, **Average**, **Count**, **Min** or **Max** on the value field. See [Binding data](/docs/widgets/binding-data).

## Alluvial options

Set these on the **Style** tab of the inspector. "Automatic" means BankSync picks a value from the chart's size and data.

| Option             | What it does                                                           | Values            | New charts start with |
| ------------------ | ---------------------------------------------------------------------- | ----------------- | --------------------- |
| **Block width**    | Width of the blocks in each stage column, in pixels.                   | Number, 0 or more | Automatic             |
| **Block gap**      | Vertical space between the blocks in a stage, in pixels.               | Number, 0 or more | Automatic             |
| **Show labels**    | Write each block’s name beside it.                                     | On or off         | Automatic             |
| **Stream opacity** | How solid the streams between stages are, from 0 (clear) to 1 (solid). | Number, 0 to 1    | Automatic             |

### Needs history

Show a note instead of the chart until the rows cover enough periods, so a first week never reads as a trend.

| Option              | What it does                                                                       | Values                          | New charts start with |
| ------------------- | ---------------------------------------------------------------------------------- | ------------------------------- | --------------------- |
| **Date field**      | The date column whose distinct periods are counted.                                | Text                            | Automatic             |
| **Period**          | What counts as one period: a day, week, month, quarter or year.                    | Day, Week, Month, Quarter, Year | Automatic             |
| **Periods needed**  | How many distinct periods the rows must cover before the chart draws (2 to 60).    | Whole number, 2 to 60           | Automatic             |
| **Waiting message** | Shown until there is enough history. Leave empty for a message naming the periods. | Text, up to 120 characters      | Automatic             |

## Shared chart styling

Every chart also has the shared styling options. These apply to this one:

- [Legend](/docs/widgets/chart-styling#legend): position, layout and which series show.
- [Axes](/docs/widgets/chart-styling#axes): titles, tick labels and number format.
- [Grid](/docs/widgets/chart-styling#grid), [title](/docs/widgets/chart-styling#title), [padding](/docs/widgets/chart-styling#padding) and [background](/docs/widgets/chart-styling#background).
- [Value labels](/docs/widgets/chart-styling#value-labels) on the marks.
- [Categories and labels](/docs/widgets/chart-styling#categories-and-labels): top N with "Other", sort order, readable labels, the handwritten callout.
- [Style](/docs/widgets/chart-styling#style): corner radius, line width, opacity and animation.
- [Tooltip](/docs/widgets/chart-styling#tooltip) on hover.
- Click to filter: clicking a mark can filter the rest of the dashboard. See [Filters and cross-filtering](/docs/dashboards/filters-and-cross-filtering).
- [Colours](/docs/widgets/chart-styling#palette): follow the dashboard palette or pick one for this chart.

## Messy data

- Until you choose two stages it asks you to "Choose at least two stages".
- Zero and negative amounts are skipped, so make money out positive first. With nothing left you see "No flows to show".
- A blank value becomes a "(blank)" node at that stage instead of breaking the path.
- The same value at two stages is two nodes that share a colour, so loops can't form.
- Thin nodes in a crowded stage fold into "Other (n)", keeping roughly eight per stage.

## On a phone

Stage names sit above the columns and node labels beside the nodes. In a narrow card the columns squeeze together and labels go first. Two or three stages still read on a phone, but more is a desktop chart.

## Related charts

- [Sankey](/docs/widgets/chart-sankey): Flows between nodes
- [Chord diagram](/docs/widgets/chart-chord): Cross-category links
- [Network graph](/docs/widgets/chart-network): Force-directed nodes + edges
- [Arc diagram](/docs/widgets/chart-arc): Linear node arcs