On this page

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 #

Terminal
npm i tally-charts
app/cash.tsx
import { 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.

Cash position, March
View of Cash position, March
Cash position, March
ItemChangeTotal
Opening cashno 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 cashno value$78.1K

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.

Margin change by driver, Q2 to Q3
View of Margin change by driver, Q2 to Q3

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 #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

axisTickSpec | 'none'5No

Value axis ticks, or 'none'. Default 5.

axisFormatAxisFormat`format`No

Axis label format. Default: format.

barSizenumber18No

Bar thickness in px. Default 18.

chartIdstring—No

Prefix for pattern and mask ids. React's useId is only unique within one root, so set this when charts render in several React roots on one page.

childrenReactNode—No—
classNamestring—No—
connectorsbooleantrueNo

Dotted lines from each bar to the next. Default true.

dataTableboolean | DataTableOptionstrueNo

Hidden data table for screen readers: true, false, or { caption, columns } to set its caption and rename column headers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
domainreadonly [number, number]the totals' range without forcing zero, rounded to nice ticksNo

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.

emptyReactNode"No data"No

Rendered instead of the plot when data is an empty array. Default "No data".

endWaterfallEndlabel "Total"No

The calculated end row. Default label "Total". In onSelect and onActiveChange its point.datum is a synthetic { label, value } created on every render, so recognise it by id === 'end', not by object identity.

endToneTone'accent' (solid)No

Default 'accent' (solid).

formatFormatSpec'number'No

Format of the start, end, totals and axis. Default 'number'.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

initialWidthnumber640No

Width used for server rendering and the first client render. Default 640.

keyboardHintstring"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 onSelect. A custom text is used as is. Set it to translate the text; "" turns it off.

marginPartial<Margin>—No—
onActiveChange(id: Id | null, point: ChartPoint<D> | null) => void—No

Called with the new active id, and its point; point.datum is the row from data.

onSelect(id: Id, point: ChartPoint<D>) => void—No

Called on click, Enter or Space; point.datum is the row from data.

rowHeightnumber64No

Default 64.

startWaterfallStart—Yes—
startToneTone'neutral' (hatched)No

Default 'neutral' (hatched).

stepLabel(step: S) => stringthe signed step value in `format`No

Text on the right of a step row. Default: the signed step value in format.

stepsreadonly S[]—Yes—
styleCSSProperties—No—
titlestring—No

Accessible name of the chart; also the default caption of the data table.

tooltipChartTooltip<S | WaterfallStart | WaterfallTotal>trueNo

Tooltip on hover and focus: true for the default pill, or a function that renders the content for a point (point.datum is your row). Default true.

widthnumber—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.