Summary

Recharts lacks native waterfall chart support. This is a frequently requested chart type used in financial reporting, budgetary analysis, and many other domains.

Current workarounds and their problems

1. Stacked transparent bar (common advice)

<Bar dataKey="invisible" stackId="a" fill="transparent" />
<Bar dataKey="visible" stackId="a" fill="#00897B" />

Problem: Breaks with negative values. When barBottom is negative, the stacking logic places bars incorrectly — all bars start from 0 instead of floating at the correct position.

2. Range bar via array dataKey (our workaround)

function waterfallRange(d) {
  return [d.barBottom, d.barTop];
}
<Bar dataKey={waterfallRange} />

This works correctly but requires:

• Pre-computing barBottom/barTop for every bar (running total logic)
• Manual domain computation that includes all bar positions
• The dataKey type doesn't accept functions returning arrays cleanly (needs as any)
• Labels/tooltips need custom components since the value is an array

Proposed feature

A first-class <WaterfallBar> component (or a waterfall prop on <Bar>) that:

1. Automatically computes bar positions from values — positive bars stack up from the running total, negative bars hang down
2. Supports "total" bars that anchor to 0 (common in waterfall charts)
3. Handles the Y-axis domain automatically to include all bar positions
4. Works with existing Recharts features — tooltips, labels, Cell coloring, animations

Minimal API sketch

<BarChart data={data}>
  <Bar dataKey="value" waterfall={{ totalKey: 'isTotal' }}>
    {data.map((d, i) => (
      <Cell key={i} fill={d.value >= 0 ? 'teal' : 'gray'} />
    ))}
  </Bar>
</BarChart>

Or as a dedicated component:

<WaterfallChart data={data} dataKey="value" totalKey="isTotal" />

Reference implementation

We built a working waterfall chart component for PolicyEngine using the range-bar workaround:

• Utils: waterfallUtils.ts — pure functions for computing positions
• Component: WaterfallChart.tsx — reusable wrapper
• Tests: waterfallUtils.test.ts — 14 unit tests

Happy to contribute a PR if the maintainers are interested in adding this natively.