WaterfallChart
Bridge chart from a starting value through signed changes and subtotals to a total.
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/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | Ordered steps. |
categoryKey | string or number field of T | required | Field naming each step. Values must be unique. |
valueKey | numeric field of T | required | Signed change for steps; absolute value for totals. |
ariaLabel | string | required | Accessible chart name. |
kindKey | string field of T | all "auto" | Field holding "total", "increase", "decrease", or "auto". Other values throw. |
colorKey | string field of T | kind color | Field holding a CSS color for a single step. |
kinds | { increase?, decrease?, total? } of { label?, color? } | Increase / Decrease / Total, status colors | Legend 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. |
plotMinWidth | number | 240 | Narrowest the plot gets beside a right legend, in px. |
valueLabels | boolean | true | Signed change, or a total's value, at each bar end. |
valueAxis | boolean | false | Value axis; labels carry the numbers by default. |
grid | boolean | true | Value grid lines, only drawn with valueAxis. |
valueDomain | [number, number] | every step with 8% padding, includes zero | Fixed value extent. |
valueTicks | number[] | rounded | Exact ticks, only used with valueAxis. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | grouped number | Amounts; positive changes get a + prefix. |
formatCategory | (value: string | number) => string | String | Step labels. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid steps exist. |
| Chart host props | see Chart | - | height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
WaterfallChartLegend | items?, placement?, size? + ul props | kind 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_LAYOUT | helpers | - | Running totals, step labels, kind colors, and size table. |
Accessibility
- Provide a meaningful
ariaLabelthat 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.