Charts
WaterfallChart
A walk from one value to another in horizontal rows: a start, one row per change, and an end that the chart works out for you. Each step is a bar floating between the running total before and after it.
When to use it #
Use WaterfallChart to explain a difference: why cash fell over a month, which drivers moved margin between two quarters, what pulls a result under its target. You pass the start and the steps (signed changes); the end row is the sum, labeled “Total” unless you set end={{ label }}. The start is hatched (startTone, neutral by default) and the end is solid (endTone, accent), so the eye reads “from” and “to”. Dotted connectors link each bar to the next, and connectors={false} removes them. stepLabel rewrites the text on the right of a step, for example to add the money behind a percentage change. The domain does not force zero, so a small change stays readable; set domain to zoom in further.
If you would rather see the running totals as vertical columns, with a cap showing each change and a note under it, use BridgeChart. A waterfall shows the changes, a bridge shows the totals they lead to.
Import #
npm i tally-chartsimport { WaterfallChart } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
format takes a preset, here currency-compact with one digit, so every total and the axis share it. start and end carry your own labels, and the steps mix gains and losses. All props are plain data.
| Item | Change | Total |
|---|---|---|
| Opening cash | no value | $84K |
| Customer payments | +$61.5K | $145.5K |
| Payroll | −$38.2K | $107.3K |
| Materials | −$24.8K | $82.5K |
| Equipment lease | −$6.5K | $76K |
| Insurance refund | +$2.1K | $78.1K |
| Closing cash | no value | $78.1K |
import { WaterfallChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'waterfall-chart/cash-flow',
title: 'Cash position, March',
rscSafe: true,
} satisfies ExampleMeta
const steps = [
{ label: 'Customer payments', value: 61500 },
{ label: 'Payroll', value: -38200 },
{ label: 'Materials', value: -24800 },
{ label: 'Equipment lease', value: -6500 },
{ label: 'Insurance refund', value: 2100 },
]
// `format` is a preset with digits, so it stays serializable (no functions): a server component can render it.
export default function CashFlow() {
return (
<WaterfallChart
title={meta.title}
description="Cash fell from $84.0K to $78.1K. Customer payments and a refund brought in $63.6K, payroll, materials and the lease took out $69.5K."
start={{ label: 'Opening cash', value: 84000 }}
steps={steps}
end={{ label: 'Closing cash' }}
format={{ preset: 'currency-compact', digits: 1 }}
/>
)
}
stepLabel writes the text on the right of each step from the step itself, here the change in points and the money behind it from meta. domain zooms in and connectors={false} drops the dotted lines. A function prop means this example is a client component.
'use client'
import { fmt, WaterfallChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'waterfall-chart/margin-drivers',
title: 'Margin change by driver, Q2 to Q3',
rscSafe: false,
} satisfies ExampleMeta
const drivers = [
{ label: 'Pricing', value: 1.2, meta: 5800 },
{ label: 'Labor mix', value: -0.9, meta: 4400 },
{ label: 'Materials', value: -1.4, meta: 6900 },
{ label: 'Callbacks', value: -0.5, meta: 2500 },
{ label: 'Job mix', value: 0.6, meta: 2900 },
]
// 'use client': `stepLabel` is a function, which a server component cannot pass.
export default function MarginDrivers() {
return (
<WaterfallChart
title={meta.title}
description="Margin slipped from 36.0% to 35.0%. Pricing and job mix added 1.8 points, materials, labor mix and callbacks took away 2.8."
start={{ label: 'Q2 margin', value: 36 }}
steps={drivers}
end={{ label: 'Q3 margin' }}
format="percent"
domain={[32, 38]}
connectors={false}
stepLabel={(s) =>
s.meta === undefined
? fmt.pts(s.value)
: `${fmt.pts(s.value)} · ${fmt.currencyCompact(s.meta)}`
}
/>
)
}
The tone of a step follows its sign: loss for a negative step and gain for a positive one. The start bar is hatched neutral and the end bar solid accent.
Props #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | Id | null | — | No | — |
animate | boolean | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
axis | TickSpec | 'none' | 5 | No | Value axis ticks, or 'none'. Default 5. |
axisFormat | AxisFormat | `format` | No | Axis label format. Default: |
barSize | number | 18 | No | Bar thickness in px. Default 18. |
chartId | string | — | No | Prefix for pattern and mask ids. React's |
children | ReactNode | — | No | — |
className | string | — | No | — |
connectors | boolean | true | No | Dotted lines from each bar to the next. Default true. |
dataTable | boolean | DataTableOptions | true | No | Hidden data table for screen readers: |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
domain | readonly [number, number] | the totals' range without forcing zero, rounded to nice ticks | No | Value domain. Default: the totals' range without forcing zero, rounded to nice ticks. When it leaves out zero, the scale runs a little past its lower end (upper end for negative values), so the start and end bars stay visible even when a total equals the domain's end; the axis still labels the domain itself. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
end | WaterfallEnd | label "Total" | No | The calculated end row. Default label "Total". In |
endTone | Tone | 'accent' (solid) | No | Default 'accent' (solid). |
format | FormatSpec | 'number' | No | Format of the start, end, totals and axis. Default 'number'. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
initialWidth | number | 640 | No | Width used for server rendering and the first client render. Default 640. |
keyboardHint | string | "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with `onSelect` | No | Instructions read with the chart when it takes keyboard focus. Default: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with |
margin | Partial<Margin> | — | No | — |
onActiveChange | (id: Id | null, point: ChartPoint<D> | null) => void | — | No | Called with the new active id, and its point; |
onSelect | (id: Id, point: ChartPoint<D>) => void | — | No | Called on click, Enter or Space; |
rowHeight | number | 64 | No | Default 64. |
start | WaterfallStart | — | Yes | — |
startTone | Tone | 'neutral' (hatched) | No | Default 'neutral' (hatched). |
stepLabel | (step: S) => string | the signed step value in `format` | No | Text on the right of a step row. Default: the signed step value in |
steps | readonly S[] | — | Yes | — |
style | CSSProperties | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tooltip | ChartTooltip<S | WaterfallStart | WaterfallTotal> | true | No | Tooltip on hover and focus: |
width | number | — | No | Fixed width in px; turns off container measuring. |
Keyboard and screen readers #
WaterfallChart is built on Chart, so it follows the same keyboard model as the other charts: it is a single tab stop, and tabbing in shows the first row with its tooltip and announces it. Arrow keys move to the previous or next row, Home and End jump to the first and last, Enter or Space selects the active row when the chart has onSelect, and Esc clears the active row. Esc is only consumed when a row is active, so an enclosing dialog still closes. The widget’s description ends with a keyboard hint (“Use arrow keys to move between points, Home and End for first and last, Escape to clear.”, plus “Press Enter to select.” with onSelect); keyboardHint replaces it, for example to translate it, and keyboardHint="" turns it off.
Screen readers get the chart title and description, then an announcement for each row the keyboard moves to. A step reads “2 of 7, Labor overruns, −1.6 pts · $7.7K, running total 36.4%”: its position, label, the step text (your stepLabel, or the signed change in format) and the running total after it. The start and end read as “1 of 7, Target, 38.0%”, without a running total. A visually hidden data table with the columns Item, Change and Total follows the chart; dataTable renames the caption and headers, or turns it off.
The full model is in the accessibility guide.