Waterfall Charts

The Waterfall Chart in SpreadJS illustrates how sequential positive and negative values affect a cumulative total. It visually breaks down each contributing factor, making it useful for analyzing profit changes, budget variance, sales performance, or inventory trends.

SpreadJS supports extensive customization options, including color palettes, bar width, legends, and connecting lines (color, width, and dash style), among others. Additional properties such as showTotal, totalLabel, and orientation provide further control over chart layout.

Below is an example of a Waterfall Data Chart.

Unique Settings

The following table outlines dedicated properties for customizing waterfall charts:

Property	Description	Sample Preview
showTotal	Controls whether the final total bar is displayed in the chart. Set to `true` to show or `false` to hide the summary column at the end.
totalLabel	Specifies the text label used for the total column (default: `"Total"`).
orientation	Determines chart orientation. Accepts `"vertical"` (default) or `"horizontal"`.
connectingLineStyle	Defines the style of the connecting lines between bars. You can customize properties such as `stroke` (line color) `strokeWidth` (line width) `strokeDasharray` (solid or dashed line pattern)

Using Code

The following sample creates a Waterfall Chart for a Year‑over‑Year Net Profit Analysis. It includes a custom chart configuration, text styling, tooltips, and animation effects.

// Basic setup
const sheet = spread.getActiveSheet();
sheet.name("Waterfall Data Chart");
const dataManager = spread.dataManager();

function createProfitsTable(dataManager) {
    const records = [
        ["Last Year Net Profit", 846.5],
        ["Product Sales Growth", 235.8],
        ["Price/Mix Improvement", 87.3],
        ["Raw Material Cost Increase", -162.7],
        ["Operating Expense Increase", -95.4],
        ["Tax Benefit", 38.6],
    ];
  const columns = ["Category", "Value"];
  return dataManager.addTable("Profits", {
    data: records.map(record => {
      const item = {};
      columns.forEach((column, index) => item[column] = record[index]);
      return item;
    }),
  });
}

const ProfitsTable = createProfitsTable(dataManager);
await ProfitsTable.fetch();

// Create a waterfall data chart
const dataChart = sheet.dataCharts.add('WaterfallChart6', 10, 10, 600, 400);
dataChart.setChartConfig({
  tableName: 'Profits',
  plots: [{
    type: GC.Spread.Sheets.DataCharts.DataChartType.waterfall,
    encodings: {
      values: [{ field: 'Value', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
      category: { field: 'Category' },
    },
    config: {
      waterfall: {
        totalLabel: 'This Year Net Profit',
        connectingLineStyle: {
          stroke: { type: 'CssColor', color: 'red' },
          strokeWidth: 2,
        },        
      },
      text: [{
        template: '{valueField.value}',
        format: { value: '0.00' },
        overlappingLabels: 'Hide',
        position: GC.Spread.Sheets.DataCharts.TextPosition.center,
        textStyle: {
          fontFamily: 'Calibri',
          fontSize: 10,
          fontWeight: 'Lighter',
          fontStyle: GC.Spread.Sheets.DataCharts.FontStyle.italic,
          color: '#333333',
        },
      }],
      tooltip: [{
        style: {
          fill: { type: 'CssColor', color: '#ffffff' },
          stroke: { type: 'CssColor', color: '#e0e0e0' },
          strokeWidth: 1,
        },
        textStyle: {
          fontFamily: 'Calibri',
          fontSize: 12,
          fontWeight: 'Lighter',
          fontStyle: GC.Spread.Sheets.DataCharts.FontStyle.italic,
          color: '#333333',
        },
      }],
      hoverAnimation: {
        duration: 400,
        easing: GC.Spread.Sheets.DataCharts.AnimationEasing.linear,
        scale: 1.5,
      },
      updateAnimation: {
        startDelay: 200,
        duration: 1000,
        easing: GC.Spread.Sheets.DataCharts.AnimationEasing.linear,
      },
    },
  }],
    config: {
    header: {
      title: 'Profit Bridge: Year-over-Year Net Profit Analysis',
      padding: {
        left: 10,
        right: 10,
        top: 10,
        bottom: 20,
      },
   style: {
        fill: { type: 'CssColor', color: '#f2f2f2' },
    },
      textStyle: {
        color: 'black',
        fontSize: 18,
        fontStyle: GC.Spread.Sheets.DataCharts.FontStyle.italic,
        fontWeight: 'Bold',
        alignment: GC.Spread.Sheets.DataCharts.HAlign.left,        
      },
    },
  },
});