Waterfall Chart
A waterfall chart for explaining how a starting total becomes an ending total through a sequence of additions and subtractions. Totals anchor at zero; deltas float from the running total, with dashed connectors bridging consecutive bars. Powered by Recharts.
Cash Flow Bridge
Two type: "total" anchors (opening and closing) with signed type: "delta" steps in between.
Custom Colors
totalsColor, additionsColor and subtractionsColor accept palette names or hex.
Minimal
Grid, connectors and legend can be turned off independently.
WaterfallChart
Explains how a starting total becomes an ending total through sequential additions and subtractions. Bars typed "total" anchor at zero and reset the running total; bars typed "delta" float from the previous running total, colored by sign. Dashed connectors bridge consecutive bars, and the Y axis computes nice bounds/ticks from the stacked extent. Fills its parent height; with many factors, minWidthPerBar enables horizontal scrolling.
Usage
import {
WaterfallChart,
type WaterfallChartDatum,
} from "@/components/charts/waterfall-chart"
const data: WaterfallChartDatum[] = [
{ label: "Opening", value: 1200, type: "total" },
{ label: "Inflows", value: 480, type: "delta" },
{ label: "Outflows", value: -350, type: "delta" },
{ label: "Closing", value: 1330, type: "total" },
]
<div className="h-80">
<WaterfallChart data={data} valueFormatter={(v) => `$${v}`} />
</div>Props
| Prop | Type | Default | Description |
|---|---|---|---|
| data* | WaterfallChartDatum[] | — | Ordered steps: { label, value, type: "total" | "delta" }. Totals anchor at zero (value is the absolute total); deltas are signed contributions. |
| valueFormatter | (value: number) => string | v => v.toString() | Formats Y-axis ticks, tooltip values and legend. |
| showLegend | boolean | true | Legend mapping the three roles (totals, additions, subtractions). |
| showTooltip | boolean | true | Tooltip with the step value and the running total. |
| showGridLines | boolean | true | Horizontal grid lines. |
| showConnectors | boolean | true | Dashed lines bridging the end of one bar to the start of the next. |
| totalsColor | ChartColor | string | "blue" | Color of total bars (palette name or hex). |
| additionsColor | ChartColor | string | "emerald" | Color of positive delta bars. |
| subtractionsColor | ChartColor | string | "red" | Color of negative delta bars. |
| yAxisWidth | number | auto | Pixels reserved for the Y axis; inferred from the formatted ticks when omitted. |
| axisTextSize | "xs" | "sm" | "md" | "lg" | number | "xs" | Axis label font size. |
| labelTruncateAt | number | — | Truncates long X labels with an ellipsis (full label in the tooltip). |
| minWidthPerBar | number | 52 | Minimum width per bar; when bars would get narrower, the chart scrolls horizontally instead. |
| className | string | — | Additional classes on the wrapper. The chart fills its parent — give the parent a height (e.g. h-80). |