Waterfall Chart
Show how an initial value is affected by a sequence of positive and negative changes. Waterfall charts are a staple of financial dashboards for cash flow, budgets, and variance analysis — with running totals, connector lines, and color-coded steps.
Basic Example
A quarterly cash-flow waterfall — a starting total, a series of gains and losses, and a closing total
Installation
Get started with the WaterfallChart component in just a few steps.
npx mario-charts@latest add waterfall-chartExamples
Explore different configurations and use cases for the WaterfallChart component.
Automatic Type Inference
Omit the type field and the chart infers increases and decreases from the sign of each value — only totals need to be marked explicitly
Horizontal Orientation
A horizontal budget breakdown — useful when step labels are long or you have many steps
Custom Colors
Override any of the three bar types via the colors prop
Default
green / red / blue
Custom
colors={{ increase: '#8b5cf6', decrease: '#f59e0b', total: '#0ea5e9' }}
Chart States
Built-in loading, error, and empty states
Loading
Error
Empty
API Reference
Complete TypeScript interface with all available props and configurations.
| Prop | Type | Default | Description |
|---|---|---|---|
datarequired | readonly T[] | — | Array of step objects (label, value, and optional type) to display |
x | keyof T | 'label' | Key from each object to use for the step label |
y | keyof T | 'value' | Key from each object holding the numeric value |
type | keyof T | 'type' | Key holding each step's type ('increase' | 'decrease' | 'total'). When absent, the type is inferred from the sign of the value |
colors | { increase?: string; decrease?: string; total?: string } | { increase: '#10b981', decrease: '#ef4444', total: '#3b82f6' } | Override the color used for each bar type |
orientation | 'vertical' | 'horizontal' | 'vertical' | Layout direction of the bars |
showConnectors | boolean | true | Draw the connector lines that link each step's running total to the next |
showValues | boolean | false | Render the signed delta (or absolute total) on each bar |
showLegend | boolean | false | Show the increase / decrease / total legend below the chart |
showGrid | boolean | false | Show value grid lines and axis tick labels |
gridStyle | 'solid' | 'dashed' | 'dotted' | 'dashed' | Style of the grid lines when showGrid is enabled |
height | number | 300 | Height of the chart in pixels |
loading | boolean | false | Show loading state with animated skeleton |
error | string | null | null | Error message to display |
animation | boolean | true | Enable entrance animations (respects prefers-reduced-motion) |
onBarClick | (data: T, index: number) => void | — | Callback fired when a bar is clicked |
tooltipRenderer | (data: WaterfallChartTooltipData<T>) => React.ReactNode | — | Custom tooltip render function for full control over tooltip content |
className | string | — | Additional CSS classes to apply to the container |