Waterfall Chart

Demo & usage

More examples

<sv-waterfall-chart [data]="data" title="Gross → net margin" orientation="vertical" [height]="320" />

<sv-waterfall-chart [data]="data" (barSelect)="onSelect($event)" (barHover)="onHover($event)" />

When to use

• Explaining how a starting value reaches an ending value through gains/losses.
• Financial bridges (revenue → net), inventory changes, budget variance.
• For plain category totals, use a Bar Chart.

Async states

• loading
• empty
• error
• retry

Outputs

<sv-waterfall-chart-pro>

Also in this family — SvWaterfallChartProComponent from @styloviz-pro/charts.

Inputs

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

<sv-waterfall-chart
  [data]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  [filtered]="data.filtered()"
  (retry)="data.reload()"
/>

// This component reports its state but does not emit a query, so drive
// it from your own fetch and bind the three async inputs.
readonly items = signal<Row[]>([]);
readonly loading = signal(false);
readonly error = signal<SvDataError | null>(null);

async load(): Promise<void> {
  this.loading.set(true);
  this.error.set(null);
  try {
    this.items.set(await this.api.fetchRows());
  } catch (e) {
    this.error.set(toSvDataError(e));
  } finally {
    this.loading.set(false);
  }
}

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `data`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Vertical or horizontal orientation.
• Increase / decrease / total color coding.
• Dashed connectors and data labels.
• Every point declares what it is through `kind` — `'delta'` (a step that moves the running total), `'subtotal'` (a running sum drawn from zero that does not advance it) or `'total'`. `isTotal` / `isIntermediate` remain as shorthand for the last two. Nothing is inferred any more: a point whose `value` is missing used to be read as a total and drawn as the running sum, so a row that failed to load rendered a figure the data never claimed in the position a reader trusts most.
• `value` on a `subtotal` or `total` is the figure your source **states** for it, and it is optional. The bar is always drawn from the steps before it — the connectors and every preceding bar have to agree with it — and any disagreement is reported: on the bar (`480 ≠ 500` plus a dashed outline), in a sentence under the plot, in the bar's accessible name and in the data table. `totalTolerance` widens the band two figures may sit apart before that happens; it defaults to 0, subject to a floating-point band that scales with the numbers, so `0.1 + 0.2` against `0.3` is not reported as a hole.
• `valuePolicy` decides what happens to a step this chart cannot draw — one whose `value` is absent, `NaN` or `Infinity`. A negative is not one of these: a waterfall is built out of falls as much as rises. `clamp` (default) moves the running total by nothing, marks the bar and names it under the plot; `reject` refuses the series and shows the error state. `omit` is not offered, because a bar's position is its place in a sequence and dropping one silently rewrites every total after it. `render` is not offered either — there is no honest way to draw a step of unknown size.
• Order is part of the data. Each bar starts where the last one ended, so `[+100, −50, subtotal]` and `[+100, subtotal, −50]` are different statements, and the subtotal reports 50 in one and 100 in the other. Sort before passing the series in; the component will not do it for you, including when the source is an unordered one (a `Map`, an object's keys, a `Promise.all` result).

Best practices

• Do: Color-code increases, decreases and totals consistently.
• Do: Order steps in the real sequence so the running total makes sense. The component never sorts — order is the arithmetic, not a presentation choice.
• Do: Type each point with `kind`: `'delta'`, `'subtotal'` or `'total'`. An opening balance is a `delta`, not a total — it moves the running total from zero to itself.
• Do: Pass the figure your source states for a `total` as its `value`. The chart checks it against the steps and reports any difference rather than quietly drawing its own answer.
• Tip: Label each bar with its delta and the running total for clarity.

Accessibility

• Each bar is keyboard-focusable (`role="button"`, Tab) and its `aria-label` carries the delta AND the running total after it. The running total is drawn as a bar's vertical position and spoken by a hover tooltip, so without it a keyboard reader learned every step and never where the total stood — in a chart whose whole subject is where the total stands.
• Tooltip appears on hover and on focus; Enter/Space emits `barSelect`. Color coding is paired with labels.
• A visually-hidden table lists every step in order with its step number, type, change and running total — the sequence is the meaning here, so the number is data rather than decoration. It stays when `showLegend` is off: the legend is a display option, the alternative to the plot is not.
• Whatever the chart had to alter or could not reconcile is stated in the rendered output, not in `console.warn`. A total that does not add up is the most consequential thing this chart can discover, and the person it matters to is reading a dashboard, not a browser console. The dashed outline in the plot gets a legend key, so the mark is never colour-only.