Guide / Controls / Charts

Flows

Where amounts flow from and to

When to use it. Flow volumes between nodes: energy from panels to loads, requests through services, budget through categories. Nodes stack into columns (sources left, sinks right — computed from the link graph), ribbons run between them with thickness ∝ value and a color gradient from source to target. Tapping a node with the node's in/out totals.

Type
sankey
Also titled
Sankey
Default size
3 rows × 4 columns
Symbol
arrow.triangle.branch
Docs
Docs complete
Search for it as
  • flow
  • funnel
  • diagram
  • sources
  • links
  • breakdown
Flows: Live energy flow
Rendered by the app

Fields

14 fields you can set on a sankey control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

Buzz when you touch it

Gives a small physical tap when you interact, on phones that support it.

  • noneno vibration
  • lighta faint tap
  • mediuma normal tap
  • heavya strong thump
  • softa gentle cushioned tap
  • rigida crisp hard tap
  • selectiona tiny tick like scrolling a picker
  • successa pattern that feels like done
  • warninga pattern that feels like careful
  • errora sharp pattern that feels like failed
Titlelabeltext—

The heading above the chart

Shows this text as the header above the diagram.

sankeyConfigsankeyConfigobject—

All the chart settings in one place

Holds the optional look and tap settings for the diagram.

Colortintcolor#667eea

The main colour

Colours the first node and seeds the colours of the others.

formatValueformatValuetext—

How numbers are written

Formats the throughput numbers shown next to node labels and the selection readout.

Node colorssankeyConfig.colorsstring[]—

The colours nodes cycle through

Gives each node a colour in turn; a colour set on a node itself wins.

Flow strengthsankeyConfig.linkOpacitynumber0–1step 0.050.32

How solid the flow bands are

Sets how see-through the ribbons are, from 0 invisible to 1 solid; selected ones brighten.

nodeActionsankeyConfig.nodeActionobject—

What happens when you tap a node

Runs this action when a node is tapped, passing its name and in and out totals.

Node spacingsankeyConfig.nodeSpacingnumber0–40 ptstep 110

Gap between boxes

Sets the smallest vertical gap between nodes in a column, 0 to 40 points.

Cell roundnesssankeyConfig.cellCornerRadiusnumber0–30 ptstep 1—

How round the boxes are

Rounds the node bars, 0 to 30 points; unset it is a third of the node width.

Node widthsankeyConfig.nodeWidthnumber1–40 ptstep 110

How thick the boxes are

Sets the width of each node bar, 1 to 40 points.

scrubsankeyConfig.scrubon / offfalse (off)

Slide your finger across nodes

Lets a drag move the spotlight from node to node with a tick each step; a tap still fires the action.

LabelssankeyConfig.showLabelson / offtrue (on)

Show node names

Shows or hides the node names beside the bars.

Value labelssankeyConfig.showValueson / offfalse (off)

Show the numbers

Shows or hides each node's throughput value next to its name.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
secondaryColortheme.secondaryColorcolor#FFFFFF99

Faint text colour

Colours the faintest text and ink.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you tap a nodenodetapjson

the tapped node's name with its total flow in and out

Sends only when the tap selects a node, not when it clears the selection

Example: {"name": "Item 1", "in": 3, "out": 2}

Receives

Receives
TakesFromTypeWhat it does
nodesshowhub, mqtt, http, storejson

nodes, and links between them each with an amount

nodes are re-stacked into columns and the ribbons resize to their new amounts

Example: {"nodes": [{"name": "Item 1"}, {"name": "Item 2"}], "links": [{"source": "Item 1", "target": "Item 2", "value": 3}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"nodes": [{"name": "Item 1"}, {"name": "Item 2"}, {"name": "Item 3"}, {"name": "Item 4"}], "links": [{"source": "Item 1", "target": "Item 3", "value": 3}, {"source": "Item 1", "target": "Item 4", "value": 1}, {"source": "Item 2", "target": "Item 4", "value": 2}]} then {"nodes": [{"name": "Item 1"}, {"name": "Item 2"}, {"name": "Item 3"}, {"name": "Item 4"}], "links": [{"source": "Item 1", "target": "Item 3", "value": 1}, {"source": "Item 1", "target": "Item 4", "value": 3}, {"source": "Item 2", "target": "Item 4", "value": 2}]}

Examples

3 examples, each one a control you can paste into a layout.

Live energy flow

A power-flow diagram fed live from a mesh socket, with values shown.

JSON 9 lines
{
  "type": "sankey",
  "id": "energy",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Energy (kW)",
  "sankeyConfig": { "showValues": true },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "power_flow" }, "valuePath": "sankey" }]
}

Open in CAR-TER

Flows: Live energy flow
Rendered by the app

Tap-to-inspect service traffic

Tapping a service broadcasts its in and out totals so something else can react.

JSON 11 lines
{
  "type": "sankey",
  "id": "traffic",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Requests/min",
  "sankeyConfig": {
    "nodeAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "inspect_service", "node": "{{value}}" } }
  },
  "defaultValue": "{\"nodes\":[{\"name\":\"Edge\"},{\"name\":\"API\"},{\"name\":\"DB\"},{\"name\":\"Cache\"}],\"links\":[{\"source\":0,\"target\":1,\"value\":120},{\"source\":1,\"target\":2,\"value\":80},{\"source\":1,\"target\":3,\"value\":40}]}"
}

Open in CAR-TER

Flows: Tap-to-inspect service traffic
Rendered by the app

Budget flow with scrubbing and custom colors

Where monthly income goes, with values shown and a drag that sweeps the spotlight across nodes.

JSON 16 lines
{
  "type": "sankey",
  "id": "budget",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Monthly budget",
  "tint": "#34C759",
  "sankeyConfig": {
    "showValues": true,
    "scrub": true,
    "nodeWidth": 14,
    "linkOpacity": 0.45,
    "colors": ["#34C759", "#FF9F0A", "#0A84FF"]
  },
  "defaultValue": "{\"nodes\":[{\"name\":\"Income\"},{\"name\":\"Rent\"},{\"name\":\"Food\"},{\"name\":\"Savings\"}],\"links\":[{\"source\":0,\"target\":1,\"value\":1200},{\"source\":0,\"target\":2,\"value\":500},{\"source\":0,\"target\":3,\"value\":300}]}"
}

Open in CAR-TER

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Live energy flow” on your phone.

    carterkit demo sankey --example 'Live energy flow'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

spotlights its flows — everything else fades — and fires nodeAction

Wide: [3, 4] and up. In a flow grid it auto-sizes to a ~3:2 landscape cell.

SankeyConfig

Field Type Default Description
nodeWidth number 10 Node bar width in points
cellCornerRadius number a third of nodeWidth Node corner rounding in points, 0–30
nodeSpacing number 10 Minimum vertical gap between nodes in a column
showLabels bool true Node names beside the bars
showValues bool false Throughput value alongside each label
linkOpacity number 0.32 Ribbon opacity (selection brightens involved ribbons)
colors string[] built-in palette Node color cycle (per-node color wins)
nodeAction ActionDefinition — Fired on node tap; {{value}} = {"name", "in", "out"}
scrub bool false Drag sweeps the spotlight from node to node with haptic ticks (the action still fires on tap)

Sync Payload Structure

Nodes plus source→target→value links — natural JSON or an encoded string. Endpoints may be node names or indices:

{
  "nodes": [
    { "name": "Solar", "color": "#FFD93D" },
    { "name": "Battery" },
    { "name": "House" },
    { "name": "Grid" }
  ],
  "links": [
    { "source": "Solar",   "target": "Battery", "value": 3.2 },
    { "source": "Solar",   "target": "House",   "value": 1.8 },
    { "source": "Battery", "target": "House",   "value": 2.1 },
    { "source": "Solar",   "target": "Grid",    "value": 0.9 }
  ]
}

Self-links, unknown endpoints, and zero/negative values are dropped. Cycles don't hang the layout, but a mostly-acyclic flow reads far better.

Behavior

  • Columns come from the longest path from the sources; pure sinks align to the last column; each column is vertically centered
  • Node height ∝ max(inflow, outflow); ribbons attach in far-end order so they fan instead of crossing at the bar
  • Tap a node to spotlight it (its ribbons brighten, unrelated ones fade to a whisper) and fire nodeAction; tap empty space to clear
  • scrub: true lets a drag sweep the spotlight fluidly across nodes with a tick per hand-off
  • Dataset pushes animate via the control's animation profile

Notes

  • ≤ 4 columns and ≤ ~10 nodes stay readable on a phone
  • The control's value is the dataset JSON — selection never overwrites it
  • For pairwise relationships without direction/stages, Labels is the circular sibling

Generated from ControlDocs/sankey.md. Something unclear or missing? Tell me.