Waterfall

Waterfall charts show how an initial value is built up or eroded by intermediate contributions. Positive bars float up, negatives down, and isSum / isIntermediateSum points anchor the running totals.

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: "waterfall"
    },
    title: {
        text: "2026 revenue bridge"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    xAxis: {
        categories: [
            "Start",
            "Product",
            "Services",
            "Churn",
            "Expansion",
            "H2",
            "End"
        ]
    },
    yAxis: {
        title: {
            text: "$k"
        }
    },
    plotOptions: {
        waterfall: {
            borderRadius: 3,
            dataLabels: {
                enabled: true,
                format: "{y}",
                style: {
                    fontWeight: "600"
                }
            },
            upColor: "rgba(22, 163, 74, 0.85)",
            color: "rgba(220, 38, 38, 0.85)"
        }
    },
    series: [
        {
            type: "waterfall",
            name: "Revenue",
            data: [
                {
                    name: "Start",
                    y: 420
                },
                {
                    name: "Product",
                    y: 180
                },
                {
                    name: "Services",
                    y: 90
                },
                {
                    name: "Churn",
                    y: -65
                },
                {
                    name: "Expansion",
                    y: 120
                },
                {
                    name: "H2",
                    isIntermediateSum: true,
                    color: "#06b6d4"
                },
                {
                    name: "End",
                    isSum: true,
                    color: "#00968c"
                }
            ]
        }
    ]
});

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

Live examples

Revenue bridge

Contributions stack on the running total; isIntermediateSum closes the half-year subtotal, isSum anchors the final bar.

TypeScript

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

const chart = chartAtom({
    chart: {
        type: "waterfall"
    },
    title: {
        text: "2026 revenue bridge"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    xAxis: {
        categories: [
            "Start",
            "Product",
            "Services",
            "Churn",
            "Expansion",
            "H2",
            "End"
        ]
    },
    yAxis: {
        title: {
            text: "$k"
        }
    },
    plotOptions: {
        waterfall: {
            borderRadius: 3,
            dataLabels: {
                enabled: true,
                format: "{y}",
                style: {
                    fontWeight: "600"
                }
            },
            upColor: "rgba(22, 163, 74, 0.85)",
            color: "rgba(220, 38, 38, 0.85)"
        }
    },
    series: [
        {
            type: "waterfall",
            name: "Revenue",
            data: [
                {
                    name: "Start",
                    y: 420
                },
                {
                    name: "Product",
                    y: 180
                },
                {
                    name: "Services",
                    y: 90
                },
                {
                    name: "Churn",
                    y: -65
                },
                {
                    name: "Expansion",
                    y: 120
                },
                {
                    name: "H2",
                    isIntermediateSum: true,
                    color: "#06b6d4"
                },
                {
                    name: "End",
                    isSum: true,
                    color: "#00968c"
                }
            ]
        }
    ]
});

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

Cost breakdown

All-negative contributions from a fixed budget — the same mechanics, upside down. Data labels can format negatives explicitly.

TypeScript

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

const chart = chartAtom({
    chart: {
        type: "waterfall"
    },
    title: {
        text: "Where the budget went"
    },
    credits: {
        enabled: false
    },
    colors: [
        "#00968c",
        "#06b6d4",
        "#d97706",
        "#7c3aed",
        "#dc2626",
        "#16a34a",
        "#0172ad",
        "#9333ea"
    ],
    legend: {
        enabled: false
    },
    xAxis: {
        categories: [
            "Budget",
            "Salaries",
            "Infra",
            "Marketing",
            "Tools",
            "Left"
        ]
    },
    yAxis: {
        title: {
            text: "$k"
        }
    },
    plotOptions: {
        waterfall: {
            borderRadius: 3,
            dataLabels: {
                enabled: true,
                format: "{y}"
            },
            upColor: "#d97706"
        }
    },
    series: [
        {
            type: "waterfall",
            name: "Budget",
            data: [
                {
                    name: "Budget",
                    y: 1000,
                    color: "#7c3aed"
                },
                {
                    name: "Salaries",
                    y: -520
                },
                {
                    name: "Infra",
                    y: -180
                },
                {
                    name: "Marketing",
                    y: -140
                },
                {
                    name: "Tools",
                    y: -60
                },
                {
                    name: "Left",
                    isSum: true,
                    color: "#00968c"
                }
            ]
        }
    ]
});

// 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 waterfall charts. See the full Highcharts API for everything else.

Option	Type	Default	Description
`chart.type`	"waterfall"	—	Requires highcharts-more (auto-loaded by mates-charts).
`series[].data[].isSum`	boolean	false	Bar shows the running total.
`series[].data[].isIntermediateSum`	boolean	false	Subtotal that resets the running sum.
`plotOptions.waterfall.upColor`	string	—	Colour for positive contributions.
`plotOptions.waterfall.color`	string	—	Colour for negative contributions and sums.
`series[].data[].color`	string	—	Per-point override — highlight totals.
`plotOptions.series.dataLabels.enabled`	boolean	false	Print each contribution.