WaterfallChart
Charts

WaterfallChart

Displays signed changes between opening and closing totals.

Component behavior

WaterfallChart displays sequential contributions to a running total. Each floating bar begins at the preceding bar’s ending value and shows a signed change.

Use cases
  • Signed changes between opening and closing totals.
  • Signed contributions, where some steps add and others subtract.
  • Financial breakdowns with intermediate subtotals.
Alternatives

BarChart: values are independent category totals.

FunnelChart: each stage is a subset of the preceding stage.

DonutChart: categories are proportions of one total.

LineChart: the task requires a multi-period time series.

Props

A WaterfallItem is a label and a value whose meaning depends on total. Without it, value is a signed delta applied to the running level. With total: true it is an absolute level: the bar is drawn from zero to that value and the running level is reset to it. The running level starts at zero, so a bridge normally opens with a total anchor. Order matters: nothing is sorted.

WaterfallChartProps props
PropTypeDefaultDescription
itemsWaterfallItem[]—Bridge steps in order. Deltas by default; absolute anchors when total is true, which also resets the running level. Zero is always inside the domain, so bars can float above or below it.
heightnumber96Plot area height in pixels, excluding the legend and axis row. The plot reserves 14px at the top for value labels.
upColorstring"var(--m-color-ok)"Bars with a value ≥ 0. A zero delta counts as up and still draws a 2px border rather than nothing.
downColorstring"var(--m-color-err)"Bars with a negative value.
totalColorstring"var(--m-color-border-strong)"Color for total bars regardless of value sign.
showValuesboolean—Displays each total value or signed delta above its bar.
formatValue(value: number) => string—Formats label magnitudes. Defaults to en-US number formatting. Delta signs are added separately.
legend{ label: string; color: string }[]—Explicit legend entries. Nothing is inferred from the colors in use, so the labels and swatches are yours to keep in sync.
renderTooltip(index: number) => ReactNode—Tooltip body for the hovered item index. Anchored to the plot and flipped past the midpoint, so the last bars stay inside the card.

Examples

Revenue bridge

Dashed connectors link each ending value to the next starting value. showValues labels totals with their level and changes with a signed delta. The chart has no y-axis.

WaterfallChart

Crossing zero

The vertical domain includes zero. Negative running totals render below zero. A zero reference line appears when a value crosses zero.

WaterfallChart negative

Subtotals mid-bridge

Set total: true on an intermediate item to render a subtotal. The bar starts at zero and resets the running level to the supplied value.

WaterfallChart subtotals

Tooltips instead of labels

Value labels may overlap as bar counts increase. Disable showValues and use renderTooltip to display details by item index. Hovering dims other columns to 45% opacity.

WaterfallChart tooltip
ImportTSX
import { WaterfallChart } from "@solarius/onset";
import type { WaterfallItem } from "@solarius/onset";

<WaterfallChart
  items={[
    { label: "Start", value: 1000, total: true },
    { label: "Sales", value: 400 },
    { label: "Refunds", value: -150 },
    { label: "End", value: 1250, total: true },
  ]}
  showValues
  formatValue={(v) => `$${v.toLocaleString("en-US")}`}
/>;