mailinapp
Documentation menu

Sankey block

Proportional flow bands between named nodes — From, To, and Value rows, e.g. traffic source → landing page → conversion. It's the shape for tracing where volume goes as it moves through a sequence of stages, when a plain funnel's single linear sequence isn't enough to show branching paths.

How it works

Unlike every sibling chart in this family, a sankey diagram's nodes aren't authored directly — there's no "node" column to fill in at all. Instead, nodes are derived from whichever labels repeat across the From and To columns: type "Visited" as a From value on one row and a To value on another, and it's the same node both times. Each node's left-to-right position (which vertical layer it sits in) is computed too, via a longest-path pass over the directed graph your rows describe — a node with no inflow starts at the leftmost layer, and every other node sits one layer past its furthest-upstream predecessor. None of this is something you position by hand.

Every link's value is a plain positive quantity — a flow has no meaningful "negative" reading, so a zero or negative authored value is dropped at grouping time rather than plotted as a backwards or zero-width band. A self-loop (a row whose From and To are the same label) is skipped outright, since a node flowing into itself has no meaningful band in a left-to-right layout. Repeated rows describing the same From/To pair are summed together, not overwritten — two rows both saying "Referral → Signed up" really do mean twice as much flow, unlike a single measurement that a later edit should replace.

A link's color defaults to its source node's own color (the conventional "colored by origin" sankey read) unless you override it per row via the optional Flow color cell. Node colors themselves aren't directly authorable — a node simply takes the next fixed color slot in first-seen order, the same identity-based color assignment every other chart in this family uses.

Past the node or link cap — 12 nodes, 24 links — an overflow node is dropped, not folded. That's a deliberate difference from how the pie or treemap chart handles overflow: merging two distinct flow endpoints into one synthetic "Other" node would misrepresent what the diagram is actually showing, since a sankey's whole point is tracing distinct paths, not summarizing a share of a whole. Any link whose source or target got dropped along with a cut node is dropped too. The data table, however, still lists every row you authored regardless of whether it made it into the drawn diagram — including flows a cyclic authoring mistake (A → B → A) leaves un-drawn but still real — so nothing you typed silently vanishes from view.

Configurable fields:

  • Chart title — optional heading text above the chart.
  • Flows (from, to, value) — the row-list: a From label, a To label, a numeric Value, and an optional per-flow Flow color override.
  • Background color, padding, border and border radius on the card.
  • Title color/size and legend color/size — text styling for the heading and the legend/table text beneath the image.

If no valid flow rows are authored yet (every row blank, self-looping, or non-positive), the block renders its title and card chrome with a plain "Add at least one row of flow data (from, to, value) to render this chart" notice instead of the image.

Examples

A user-journey diagram — Visited → Signed up → Purchased, with a second branch to Bounced and a third to Churned — makes drop-off and branching visible in one image where a funnel would force everything into a single line. A budget-allocation flow (Revenue → Department budgets → Line items) gives a finance recap a visual trace of where money moves stage by stage. A support team can flow ticket volume from Channel (email/chat/phone) through Category (billing/bug/how-to) to Resolution (resolved/escalated), surfacing which channels feed which outcomes.

What the static fallback looks like

<div style="margin:12px 0;background-color:#ffffff;padding:16px">
  <p style="margin:0 0 8px;font-weight:600;font-size:15px;color:#111827">Signup journey</p>
  <img src="https://mailinapp.com/api/analytics/chart?d=eyJ0eXBlIjoi...&s=3f9a2b1c..." width="560" height="360"
       alt="Flow diagram: Visited to Signed up 120, Visited to Bounced 380, Signed up to Purchased 45, Signed up to Churned 75" />
  <table style="width:100%;border-collapse:collapse;margin-top:4px">
    <tr>
      <th style="text-align:left;padding:4px 8px;font-weight:600">From</th>
      <th style="text-align:left;padding:4px 8px;font-weight:600">To</th>
      <th style="text-align:left;padding:4px 8px;font-weight:600">Value</th>
    </tr>
    <tr>
      <td style="padding:4px 8px">Visited</td>
      <td style="padding:4px 8px">Signed up</td>
      <td style="padding:4px 8px">120</td>
    </tr>
  </table>
</div>

The alt text lists every drawn flow band; the table lists every authored row, including any that a node/link cap or a cyclic layout left undrawn.

Related