Waterfall charts
Explain how signed changes move one balance from an opening to a closing total.
Use waterfall when the sequence of changes is the story. The order of the data rows is the order of the chart; Szum calculates every running balance. For real-data examples and a template to paste, see the waterfall chart maker.
Bind the steps
category.field names each visible step, values.field names one numeric amount, and stepKind.field names a field containing start, change, subtotal, or total.
The optional opening start is first. At least one signed change follows, and one total closes the sequence. A subtotal reports the running balance without resetting it. Start and change rows carry finite numbers; subtotal and total rows carry explicit null amounts. Every step needs a distinct category label, including after formatting.
There is no series, aggregation, sorting, or logarithmic balance scale. Rearranging source rows changes the calculation.
The step axis always uses categories in source order. Its scale is fixed, so the editors do not offer a separate scale choice for that axis.
Focus on changes
Omit focus to draw opening, subtotal, and closing balances from zero. Set focus: "changes" when a large balance makes smaller changes hard to read: changes keep their before and after endpoints, while balances become labeled points. Focus changes only presentation; the source rows and calculated balances stay the same.
Labels, connectors, and color
Connectors and native value labels appear by default. Bar values sit outside at the signed endpoint; set labels.position to "auto" to move labels inside when they fit, or "inside" to keep them inside. Use connectors: false or labels: false to hide them. Built-in palettes use neutral totals, green or teal increases, and warm red decreases; color.increase, color.decrease, and color.total override the selected theme’s semantic colors.
Generated SVG step descriptions are English. For a chart with a non-English locale, Szum omits that generated narration; author accessibilityDescription in the chart’s language.
Fixed reference lines may target the step or balance axis. Annotations can attach to a step’s painted mark or an exact coordinate. Statistical references need an explicit population decision and are not part of this family.
Properties
| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-09-26" | – | Required. The chart config version. |
type | ChartType | – | Required. The chart family. |
title | string | – | Chart title. |
subtitle | string | – | Supporting text beneath the title. |
caption | string | – | Caption below the chart for a source, methodology note, or date. |
accessibilityDescription | string | – | Accessible description of the chart's meaning. |
headerAlign | "start" | "center" | "end" | theme default | Horizontal alignment for the title and subtitle. Omit it to use the selected theme's alignment. |
locale | string | "en-US" | Locale identifier accepted by JavaScript Intl and associated with the chart content, such as en, pl, or zh-Hant. |
theme | ThemeName | "editorial" | One of 6 built-in themes. |
themeOverrides | ThemeOverrides | – | Override individual theme properties. |
category | { field: string; format?: string } | – | Required. Ordered step label field. |
values | { type: "long"; field: string; scale?: LinearScale; format?: string; currency?: string } | – | Required. Single numeric amount field; computed rows contain null. |
stepKind | { field: string } | – | Required. Field containing start, change, subtotal, or total. |
focus | "changes" | – | Emphasize changes and show balances as points. |
connectors | boolean | true | Connect consecutive running balances. |
labels | WaterfallLabels | – | Display each step's native value outside by default; auto and inside are available for bars. |
color | WaterfallColor | – | Increase, decrease, and total colors. |
categoryAxis | boolean | AxisOptions | – | Category-axis display options. |
valueAxis | boolean | AxisOptions | – | Balance-axis display options. |
plotBorder | boolean | theme default | Full plot border, independent of axis visibility. |
annotations | CartesianAnnotation[] | – | Step annotations. |
references | WaterfallReference[] | – | Fixed reference lines. |