DitherCharts

Waterfall chart

Updated

WaterfallChart floats one bar per row from the running total, solid when it rises and striped when it falls, with a total at half tone and dashed connectors between the bars. Like every DitherCharts chart, it fills its container's width, animates in, moves a cursor with the arrow keys, and keeps a data table for screen readers.

Example

Waterfall

Monthly cash flow, rises solid and falls striped, with an end total

Waterfall

Install it:

npx dithercharts add waterfall-chart

Then use it:

import { WaterfallChart } from "@/components/dithercharts/waterfall-chart"
import type { ChartConfig } from "@/components/dithercharts/chart-config"

const chartData = [
  { month: "Jan", cash: 120 },
  { month: "Feb", cash: 80 },
  { month: "Mar", cash: -60 },
  { month: "Apr", cash: 140 },
  { month: "May", cash: -30 },
  { month: "Jun", cash: 90 },
  { month: "Jul", cash: -110 },
  { month: "Aug", cash: 60 },
]

const chartConfig = {
  cash: { label: "Cash" },
} satisfies ChartConfig

export function ChartWaterfall() {
  return (
    <WaterfallChart
      data={chartData}
      config={chartConfig}
      xKey="month"
      dataKey="cash"
      label="Cash flow"
    />
  )
}

Installing needs DitherCharts Pro. See pricing.

Cash flow
monthCashRunning
Jan+120120
Feb+80200
Mar-60140
Apr+140280
May-30250
Jun+90340
Jul-110230
Aug+60290
Total-290
import { WaterfallChart } from "@/components/dithercharts/waterfall-chart"
import type { ChartConfig } from "@/components/dithercharts/chart-config"

const chartData = [
  { month: "Jan", cash: 120 },
  { month: "Feb", cash: 80 },
  { month: "Mar", cash: -60 },
  { month: "Apr", cash: 140 },
  { month: "May", cash: -30 },
  { month: "Jun", cash: 90 },
  { month: "Jul", cash: -110 },
  { month: "Aug", cash: 60 },
]

const chartConfig = {
  cash: { label: "Cash" },
} satisfies ChartConfig

export function ChartWaterfall() {
  return (
    <WaterfallChart
      data={chartData}
      config={chartConfig}
      xKey="month"
      dataKey="cash"
      label="Cash flow"
    />
  )
}

Install

Charts install with DitherCharts Pro. See Installation to log in and import the stylesheet.

npx dithercharts add waterfall-chart

Props

WaterfallChart props
PropTypeDefaultDescription
datarequiredType readonly ChartRow[]Default –One row per change, left to right, e.g. { month: "Jan", cash: 120 }; a missing change counts as 0.
configrequiredType ChartConfigDefault –An entry for dataKey: the change's label.
xKeyrequiredType stringDefault –The row key that holds the x label, e.g. "month".
dataKeyrequiredType stringDefault –The row key that holds each change, e.g. "cash".
totalKeyType stringDefault –The row key that marks a subtotal (any value but 0, "" or none): its bar runs from 0 to the running total, its own value ignored.
totalType booleanDefault trueA final bar from 0 to the running total.
totalLabelType stringDefault "Total"The final bar's x label.
labelrequiredType stringDefault –Accessible name, e.g. "Cash flow". Also captions the table twin.
connectorsType booleanDefault trueA dashed line from each bar's end to the next bar's start.
valueLabelsType booleanDefault trueEach change, signed, past its bar's end, and each total over its bar.
yAxisType booleanDefault falseValue labels beside the grid lines.
tooltipType TooltipOptionsDefault –The tooltip's label, and the bar it opens on at rest.
styleType StyleIdDefault "bayer4"Dither style.
animationType "develop" | "none"Default "develop"Entrance animation; reduced motion always shows the final frame.
heightType numberDefault 300Height in CSS pixels; the width fills the container.
cellType numberDefault 3Dither cell size in CSS pixels.
classNameType stringDefault –Classes on the chart's outer figure.

Styles

The dither styles style takes:

  • "bayer2"
  • "bayer4"
  • "bayer8"
  • "blue-noise"
  • "halftone"
  • "crosshatch"
  • "pixel"
  • "stipple"
  • "engraved"
  • "mezzotint"
  • "woodcut"
  • "floyd-steinberg"
  • "atkinson"
  • "riemersma"

Keyboard and accessibility

The chart is one Tab stop. Focusing it from the keyboard puts the cursor on the first bar, or where the keys last left it; moving focus away clears it. The keys stop at the ends.

Chart keys
KeyAction
Left arrow Right arrowPrevious / next bar
Home EndFirst / last bar
EscapeDismiss the cursor

Screen readers

  • The chart's label names it, says how many bars it has and lists these keys.
  • Each key press is announced in a polite live region. Moving the pointer is silent.
  • The table button under the chart shows its data as a table. Screen readers can reach the table even while it's hidden; clicking a row moves the cursor there and announces it.
  • With legend, each entry is a toggle button. The last one showing can't be hidden, but its button stays focusable.

On a touch screen, a tap pins the cursor and a tap outside the chart dismisses it.

See every waterfall chart example