0|

Waterfall Chart

Documentation Index

Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.

Bridges, deltas, and totals stacked as one composable BeeChart

apidocgithub
Basic Chart

Installation

pnpm dlx shadcn@latest add @beecharts/waterfall-chart

Usage

The waterfall chart is composible on top of stacked <Bar /> geometries (transparent “base” + visible segment). Provide rows with semantic WaterfallType (start, increase, decrease, total) encoded at typeKey (defaults to "type"), display names (nameKey), deltas (valueKey), gradients via chartConfig. Compose <Grid />, <XAxis />, <YAxis />, <Bars />, <Tooltip />, <Legend /> as needed plus optional backgroundVariant on the root — remaining behavior forwards into Recharts <BarChart />; see BarChart docs when extending through chartProps.

import {
  BeeWaterfallChart,
  Bars,
  Grid,
  XAxis,
  YAxis,
  Tooltip,
  Legend,
} from "@/components/beecharts/charts/waterfall-chart";
<BeeWaterfallChart
  config={chartConfig}
  data={rows}
  nameKey="name"
  valueKey="amount"
  typeKey="type"
  backgroundVariant="dots"
>
  <Grid vertical={false} />
  <XAxis />
  <YAxis />
  <Bars isClickable glowingBars={["product-a"]} />
  <Tooltip />
  <Legend isClickable />
</BeeWaterfallChart>

Interactive Selection

Set isClickable on <Bars /> and <Legend /> as needed — onSelectionChange carries { dataKey, value } | null, where dataKey aligns with names from nameKey and values reflect stacking math (start resets running totals, totals span full magnitude, deltas offset previous balance):

<BeeWaterfallChart
  config={chartConfig}
  data={rows}
  nameKey="name"
  valueKey="amount"
  onSelectionChange={(selection) => {
    if (selection) {
      console.log("Selected:", selection.dataKey, selection.value);
    } else {
      console.log("Deselected");
    }
  }}
>
  <Grid />
  <XAxis />
  <YAxis />
  <Bars isClickable />
  <Legend isClickable />
  <Tooltip />
</BeeWaterfallChart>

Loading State

isLoading='true'

Examples

Intro animation

Bars grow in on first paint with a staggered motion.dev reveal (Recharts’ built-in bar animation is disabled, same as other Bee charts). Control order with animationType on the root — "left-to-right" (default), "right-to-left", "center-out", "edges-in", or "none". Respects the OS reduce-motion preference.

<BeeWaterfallChart animationType="center-out" ...>

Glowing Bars

glowing

API Reference

The chart is composed of several parts. The props below are grouped by the component they belong to.

BeeWaterfallChart

The root container bridging raw financial rows → cumulative stack-friendly records (base + barValue). Tracks selection highlighting, translucent reference line (y={0}), rounded rect edges, gradients, legends, glowing filters, shimmer skeleton overlays when isLoading.

PropTypeDefaultDescription
config*Record<string, ChartConfig[string]>–

Keys correspond to categorical nameKey values powering gradients + legends.

data*TData[]–

Rows with nameKey, numeric valueKey, typed WaterfallType semantics at typeKey.

nameKey*keyof TData & string–

Display + identity column also fed to stacked <defs /> gradient ids.

valueKey*keyof TData & string–

Contribution magnitudes interpreted per WaterfallType.

typeKeykeyof TData & string"type"

Selects categorical driver for bridging logic (start, increase, decrease, total).

children*ReactNode–

Compose <Bars />, <Grid />, <XAxis />, <YAxis />, <Legend />, <Tooltip />, optional root backgroundVariant, and escapes through chartProps.

classNamestring–

Extra classes forwarded to <ChartContainer />.

barRadiusnumber4

Corner rounding for waterfall rectangles.

backgroundVariantBackgroundVariant–

Draws <ChartBackground /> underneath the chart (same pattern as bar and scatter charts).

defaultSelectedBarstring | nullnull

Pre-select waterfall slice by nameKey string (null clears).

onSelectionChange(selection: { dataKey: string; value: number } | null) => void–

Mirrors clicks on stacked segments + legend parity with <Bars />.

isLoadingbooleanfalse

Applies motion shimmering placeholders while withholding final geometry transitions.

loadingBarsnumber6

Number of placeholder categories during loading sequences.

animationTypenone|left-to-right|right-to-left|center-out|edges-in"left-to-right"

Staggered grow-in order on first render (motion.dev, not Recharts).

chartPropsComponentProps<typeof BarChart>–

Native Recharts props forwarded to <BarChart />; refer to Recharts BarChart.

Bars

Configuration slot translating user intent (isClickable, glowingBars) into per-rect handlers + defs.

PropTypeDefaultDescription
isClickablebooleanfalse

Enables pointer toggling. Dimming applies whenever a bar is selected (legend, default, or click).

glowingBarsstring[][]

Subset of nameKey values receiving glow <filter />.

Grid

Cartesian scaffolding with sane defaults balancing dense financial labeling.

PropTypeDefaultDescription
verticalbooleanfalse

Defaults to horizonal-only separators unless explicitly enabled for dual-axis overlays.

strokeDasharraystring"3 3"

Dash forwarded to <CartesianGrid />.

…gridProps––

Forwarded verbatim; see CartesianGrid.

XAxis

Category axis keyed to nameKey, hidden during loading shimmer.

PropTypeDefaultDescription
type"category" | ..."category"

Forwarded <XAxis type /> while automatically binding dataKey={nameKey}.

tickMarginnumber8

Comfortable breathing room for rotated tick labels without colliding stacking math.

…axisProps––

Forwarded extras per Recharts XAxis.

YAxis

Numeric axis bridging positive / negative deltas with zero reference line synergy.

PropTypeDefaultDescription
type"number" | ..."number"

Forwarded verbatim when not loading (width resolves to 'auto' by default inside component).

tickMarginnumber8

Space between ticks + labels.

…axisProps––

Additional props forwarded untouched; consult Recharts YAxis.

Tooltip

Selection-aware formatter with subdued crosshair fill (muted translucent band).

PropTypeDefaultDescription
variantdefault|frosted-glass"default"

Tooltip motif.

roundnesssm|md|lg|xl"lg"

Tooltip radius presets.

defaultIndexnumber–

Forces tooltip spotlight on categorical index zero while idle pointers.

Legend

Per-bridge legends mirroring clickable selection state.

PropTypeDefaultDescription
variantsquare|circle|circle-outline|rounded-square|rounded-square-outline|vertical-bar|horizontal-bar–

Legend marker motifs.

alignleft|center|right"right"

Horizontal alignment (Bee waterfall defaults tighter to chart gutter).

verticalAligntop|middle|bottom"top"

Vertical stacking.

isClickablebooleanfalse

Legend entries toggle shared selection; dimming follows selectedBar even when <Bars /> is not clickable.

Waterfall data semantics

WaterfallType strings drive preprocessing before bars render (start, increase, decrease, total).

PropTypeDefaultDescription
WaterfallTypestart|increase|decrease|total–

Determines how <BeeWaterfallChart /> maps each row onto transparent base offsets vs visible segments — total resets running sums to anchored bars, decreases invert direction while preserving stacked geometry, increases extend running totals, start seeds initial balances from absolute magnitudes.

Did you like the content?