WaterfallChart

Bridge chart from a starting value through signed changes and subtotals to a total.

stable

Quick Preview

Cash bridge

Opening balance to net position

  • Increase
  • Decrease
  • Total

Usage

import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
import { WaterfallChart } from "@giddaa-housing/ui/waterfall-chart";

<ChartCard>
  <ChartHeader><ChartTitle>Cash bridge</ChartTitle></ChartHeader>
  <WaterfallChart
    data={[
      { label: "Open", value: 60, type: "total" },
      { label: "Q1", value: 25 },
      { label: "Q2", value: -15 },
      { label: "Net", value: 70, type: "total" },
    ]}
    categoryKey="label"
    valueKey="value"
    kindKey="type"
    ariaLabel="Cash bridge from 60 to 70"
  />
</ChartCard>

Each row is a signed change from the running total. Rows whose kindKey field is "total" are drawn from zero and reset the running total (openings, subtotals, closings); "auto" or an empty value colors a change by its sign. Labels and tooltips show each step's own change, and tooltips add the running total. The increase / decrease / total legend sits to the right of the plot; use legend="bottom" or false to move or hide it. Compose title and description with ChartCard.

Examples

Default

Totals are marked explicitly with kindKey. Middle steps float between running totals.

Cash bridge

Opening balance to net position

  • Increase
  • Decrease
  • Total

Horizontal

Use orientation="horizontal" for long labels or many steps.

Revenue movement

Long labels read better horizontally

  • Increase
  • Decrease
  • Total

Plot only

createWaterfallChartDefinition is the plot the component uses, without a legend. Pass it to Chart to skip card chrome, and add WaterfallChartLegend where you want the key.

Plot only

Use the chart without ChartCard chrome.

  • Increase
  • Decrease
  • Total
import { Chart } from "@giddaa-housing/ui/chart";
import {
  createWaterfallChartDefinition,
  WATERFALL_CHART_LAYOUT,
  WaterfallChartLegend,
} from "@giddaa-housing/ui/waterfall-chart";

const definition = createWaterfallChartDefinition({ data, categoryKey: "label", valueKey: "value", kindKey: "type" });

<Chart definition={definition} height={WATERFALL_CHART_LAYOUT.md.height} ariaLabel="Quarterly bridge" />
<WaterfallChartLegend placement="bottom" />

Props

Prop/APITypeDefaultDescription
datareadonly T[]requiredOrdered steps.
categoryKeystring or number field of TrequiredField naming each step. Values must be unique.
valueKeynumeric field of TrequiredSigned change for steps; absolute value for totals.
ariaLabelstringrequiredAccessible chart name.
kindKeystring field of Tall "auto"Field holding "total", "increase", "decrease", or "auto". Other values throw.
colorKeystring field of Tkind colorField holding a CSS color for a single step.
kinds{ increase?, decrease?, total? } of { label?, color? }Increase / Decrease / Total, status colorsLegend and tooltip label and color per kind.
size"sm" | "md" | "lg"inherited, otherwise "md"Plot, type, bars, connectors, and legend markers.
orientation"vertical" | "horizontal""vertical"Direction of the bridge.
legend"right" | "bottom" | false"right"Kind legend placement. A right legend wraps under the plot when the plot would be narrower than plotMinWidth.
plotMinWidthnumber240Narrowest the plot gets beside a right legend, in px.
valueLabelsbooleantrueSigned change, or a total's value, at each bar end.
valueAxisbooleanfalseValue axis; labels carry the numbers by default.
gridbooleantrueValue grid lines, only drawn with valueAxis.
valueDomain[number, number]every step with 8% padding, includes zeroFixed value extent.
valueTicksnumber[]roundedExact ticks, only used with valueAxis.
tooltipbooleantrueHover and keyboard tooltip.
formatValue(value: number) => stringgrouped numberAmounts; positive changes get a + prefix.
formatCategory(value: string | number) => stringStringStep labels.
emptyMessageReactNode"No data to display"Shown when no valid steps exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
WaterfallChartLegenditems?, placement?, size? + ul propskind items, "right"The legend on its own.
waterfallKindItems(kinds?)function-Legend items honoring kinds overrides.
createWaterfallChartDefinition(options)function-Same options without the legend; returns an extensible TanStack definition.
prepareWaterfallData, formatWaterfallStep, WATERFALL_CHART_COLORS, WATERFALL_CHART_LAYOUThelpers-Running totals, step labels, kind colors, and size table.

Accessibility

  • Provide a meaningful ariaLabel that states the start and end values.
  • Keep steps in chronological or logical order so the bridge tells a coherent story.
  • Reserve "total" for genuine subtotals such as opening and net values.
  • Do not rely on color alone; keep the legend and value labels visible when exact comparison matters.

On this page