Waterfall Chart

Waterfall charts show how an initial value is affected by a series of positive and negative changes. They are commonly used in financial analysis to visualize profit/loss statements, budget changes, or any sequential cumulative data.

Interface

WaterfallChart Props

interface WaterfallChartProps {
  // Required properties
  data: WaterfallChartData;

  // Optional properties
  custom?: Partial<WaterfallChartCustom>;
  title?: string;
  getScale?: (data: WaterfallChartData) => WaterfallChartScale;
}

Data Structure

type WaterfallChartData = {
  labels: string[];        // Category labels
  values: number[];        // Change values (positive or negative)
  totalIndices?: number[]; // Indices that represent totals
  title?: string;          // Chart title
};

type WaterfallChartScale = {
  min: number;     // Minimum value
  max: number;     // Maximum value
  step: number;    // Step interval
};

Basic Usage

import Widget from '@meursyphus/flitter-react';
import { WaterfallChart } from '@meursyphus/headless-chart';

const data = {
  labels: ['Start', 'Revenue', 'Costs', 'Tax', 'Net Profit'],
  values: [1000, 500, -300, -100, 0],
  totalIndices: [0, 4],
  title: 'Profit Breakdown'
};

function BasicWaterfallChart() {
  return (
    <Widget
      width="600px"
      height="400px"
      widget={WaterfallChart({ data })}
    />
  );
}

Chart Components

Waterfall Chart consists of the following hierarchical structure:

WaterfallChart
└── Layout (overall layout)
    ├── Title (chart title)
    ├── Legend (legend items)
    └── Plot (plot area)
        ├── XAxis (X-axis)
        ├── YAxis (Y-axis)
        ├── Grid (grid lines)
        └── Series (data series)
            ├── Bar (increase/decrease/total bars)
            └── Connector (connecting lines between bars)

Customizable Elements

You can customize the following components through the custom prop:

Component	Args	Description
`layout`	`{ title, legends, plot }`	Overall chart layout
`plot`	`{ xAxis, yAxis, series, grid }`	Plot area
`series`	`{ bars, connectors }`	Data series container
`bar`	`{ value, cumulative, index, label, type }`	Individual bar (type: ‘increase’ \| ‘decrease’ \| ‘total’)
`connector`	`{ fromCumulative, toCumulative, index }`	Connecting line between bars
`legend`	`{ name, index }`	Legend item
`title`	`{ name }`	Chart title
`dataLabel`	`{ value, label, type }`	Data label (type: ‘increase’ \| ‘decrease’ \| ‘total’)
`xAxis`	`{ line, labels, tick }`	X-axis structure
`yAxis`	`{ line, labels, tick }`	Y-axis structure
`xAxisLabel`	`{ name, index }`	X-axis label
`yAxisLabel`	`{ name, index }`	Y-axis label
`xAxisLine`	-	X-axis line
`yAxisLine`	-	Y-axis line
`xAxisTick`	-	X-axis tick mark
`yAxisTick`	-	Y-axis tick mark
`grid`	`{ xLine, yLine }`	Grid container
`gridXLine`	-	Vertical grid line
`gridYLine`	-	Horizontal grid line

Real-World Usage Examples

1. Custom Bar Colors by Type

const coloredWaterfall = WaterfallChart({
  data,
  custom: {
    bar: ({ value, cumulative, index, label, type }) => {
      const colors = {
        increase: '#22c55e',
        decrease: '#ef4444',
        total: '#3b82f6'
      };
      return Container({
        decoration: new BoxDecoration({
          color: colors[type],
          borderRadius: BorderRadius.circular(2)
        })
      });
    }
  }
});

2. Custom Connectors

const styledWaterfall = WaterfallChart({
  data,
  custom: {
    connector: ({ fromCumulative, toCumulative, index }) => {
      return Container({
        height: 1,
        color: '#9ca3af',
        // Dashed line connector
      });
    }
  }
});

Next Steps

For more examples, check out the demo page
Use totalIndices to mark summary bars
Color-code increases and decreases for clear visual distinction