Sankey

Sankey diagrams trace flow between nodes — energy budgets, user journeys, cost allocation. Each point is { from, to, weight }; node positions are computed automatically.

Module setup. Auto-loaded by the main mates-charts entry (Tier A). Bare-core users import the module explicitly.

import "highcharts/modules/sankey";

Usage

Create a chart atom with standard Highcharts options, then render Chart(chart) anywhere in a mates template. Every later chart.set(…) or chart.update(…) re-renders the chart — no imperative Highcharts code.

Quick start

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "sankey"
    },
    title: {
        text: "Revenue allocation"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    plotOptions: {
        sankey: {
            dataLabels: {
                enabled: true,
                format: "{point.from} → {point.to}: {point.weight}"
            }
        }
    },
    series: [
        {
            type: "sankey",
            name: "Flow",
            data: [
                {
                    from: "Revenue",
                    to: "Product",
                    weight: 420
                },
                {
                    from: "Revenue",
                    to: "Marketing",
                    weight: 180
                },
                {
                    from: "Revenue",
                    to: "Operations",
                    weight: 150
                },
                {
                    from: "Product",
                    to: "Engineering",
                    weight: 280
                },
                {
                    from: "Product",
                    to: "Design",
                    weight: 140
                },
                {
                    from: "Marketing",
                    to: "Ads",
                    weight: 110
                },
                {
                    from: "Marketing",
                    to: "Content",
                    weight: 70
                }
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Live examples

Budget flow Highcharts demo ↗

Sources on the left, destinations on the right; link thickness = weight. Nodes inherit colours from links automatically.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "sankey"
    },
    title: {
        text: "Revenue allocation"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    plotOptions: {
        sankey: {
            dataLabels: {
                enabled: true,
                format: "{point.from} → {point.to}: {point.weight}"
            }
        }
    },
    series: [
        {
            type: "sankey",
            name: "Flow",
            data: [
                {
                    from: "Revenue",
                    to: "Product",
                    weight: 420
                },
                {
                    from: "Revenue",
                    to: "Marketing",
                    weight: 180
                },
                {
                    from: "Revenue",
                    to: "Operations",
                    weight: 150
                },
                {
                    from: "Product",
                    to: "Engineering",
                    weight: 280
                },
                {
                    from: "Product",
                    to: "Design",
                    weight: 140
                },
                {
                    from: "Marketing",
                    to: "Ads",
                    weight: 110
                },
                {
                    from: "Marketing",
                    to: "Content",
                    weight: 70
                }
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Multi-stage journey

Chains of from → to links create stages automatically; null-weight links keep drop-offs visible.

TypeScript

import { html } from "mates";
import { Chart, chartAtom } from "mates-charts";

const chart = chartAtom({
    chart: {
        type: "sankey"
    },
    title: {
        text: "Onboarding journey"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    plotOptions: {
        sankey: {
            nodeAlignment: "left",
            dataLabels: {
                enabled: true,
                format: "{point.name}"
            }
        }
    },
    series: [
        {
            type: "sankey",
            name: "Journey",
            data: [
                {
                    from: "Visit",
                    to: "Signup",
                    weight: 1254
                },
                {
                    from: "Visit",
                    to: "Bounce",
                    weight: 8746
                },
                {
                    from: "Signup",
                    to: "Activated",
                    weight: 820
                },
                {
                    from: "Signup",
                    to: "Dormant",
                    weight: 434
                },
                {
                    from: "Activated",
                    to: "Paid",
                    weight: 336
                },
                {
                    from: "Activated",
                    to: "Free tier",
                    weight: 484
                }
            ]
        }
    ]
});

// render inside any mates template — give the wrapper a height:
export const MyChart = () =>
    html`<div style="height: 22rem">${Chart(chart)}</div>`;

Options reference

mates-charts passes options straight through to Highcharts — these are the keys that matter for sankey charts. See the full Highcharts API for everything else.

Option	Type	Default	Description
`chart.type`	"sankey"	—	Registered by mates-charts (Tier A) or highcharts/modules/sankey.
`series[].data`	{ from, to, weight }[]	—	Links; nodes materialise from the from/to names.
`plotOptions.sankey.nodeAlignment`	"left" \| "right" \| "center" \| "justify"	"justify"	Node column alignment.
`plotOptions.sankey.nodeWidth / nodePadding`	number	—	Node box sizing.
`series[].nodes[]`	{ id, color, offset }[]	—	Optional per-node overrides — colours, vertical offsets.
`plotOptions.sankey.dataLabels`	DataLabelsOptions	—	Label links and/or nodes — {point.from}, {point.to}, {point.weight}.