shadcn.io is an independent project built on shadcn/ui
Installation
The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.
Usage
Each row is a step: its label under xDataKey (label by default) and its signed change under the dataKey you give <Waterfall>. A row with total: true is a total.
<script setup lang="ts">
import {
BarXAxis,
ChartTooltip,
Grid,
Waterfall,
WaterfallChart,
} from "@/components/ui/charts";
const data = [
{ label: "Q1", total: true, value: 1200 },
{ label: "New sales", value: 540 },
{ label: "Upsells", value: 180 },
{ label: "Churn", value: -260 },
{ label: "Q2", total: true },
];
</script>
<template>
<WaterfallChart ariaLabel="Cash, Q1 to Q2" :data="data">
<Grid horizontal />
<Waterfall data-key="value" />
<BarXAxis />
<ChartTooltip />
</WaterfallChart>
</template>Anatomy
<Waterfall> holds everything about the bars. The axes, grid and tooltip are the same parts the bar chart uses.
<WaterfallChart :data="data">
<Grid horizontal />
<Waterfall data-key="value" :format-value="formatMoney" />
<BarXAxis />
<BarYAxis />
<ChartTooltip />
</WaterfallChart>WaterfallChart: Reads the rows left to right and gives each step a band.Grid: Horizontal guide lines behind the bars.Waterfall: The bars, the dashed connectors between them and the value labels.BarXAxis: The step labels.BarYAxis: The scale of the running total.ChartTooltip: The step's change and the running total after it.
Totals and subtotals
A row with total: true is drawn from zero. Give it a value and it resets the running total to that value, which is how a bridge starts from an opening balance. Leave the value out and the bar shows the running total so far, as a subtotal.
To flag totals with another field, pass its name to <Waterfall> as totalKey.
Labels, connectors and a closing total
Each bar is labeled with its change, and a total with its value. Dashed connectors run from the end of one bar to the next. On a dense chart, turn them off with :showValues="false" and :showConnectors="false".
If your data has no closing row, add showTotal and the chart appends one, named by totalLabel. formatValue formats the labels, the tooltip and the value axis in one go.
Customization
The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.
class goes on the chart's container, so size and spacing are utility classes.
Green and red don't suit every report. positiveFill, negativeFill and totalFill set the three colors, radius rounds the bars (4 px) and barGap on the chart sets the space between them.
rows on <ChartTooltip> receives the step's row as you wrote it, not the running total. To list the total in rows of your own, compute it into the data first.
<Waterfall
data-key="value"
negative-fill="var(--chart-5)"
positive-fill="var(--chart-2)"
:radius="2"
total-fill="var(--chart-1)"
/>Where a part renders content of its own, you pass it in. In Vue:
ChartTooltip:<template #content="{ point, index }">
Loading state
With status="loading" the bars become a shimmering skeleton bridge on the chart's own bands, and the pointer is ignored. Switch to "ready" and the real steps build in from the first.
With no rows to pass yet, render <WaterfallChartLoading /> in the chart's place.
Animation
Bars grow left to right over animationDuration (1100 ms), each one starting from where the previous bar ended. The labels and connectors fade in toward the end.
Pass :animate="false" to draw the bridge in one frame.
Theming
Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.
Gains are --chart-positive and losses --chart-negative, which is your --destructive. --chart-positive is a fixed green rather than a theme token, so set it yourself if your theme has a green of its own. Totals use --chart-1.
| Token | Default | Paints |
|---|---|---|
--chart-positive | a fixed green | values above the baseline in profit and loss |
--chart-negative | --destructive | values below the baseline in profit and loss |
--chart-1 | your theme's | the first series |
--chart-foreground-muted | --muted-foreground mixed toward --background | skeletons and faded marks |
--chart-grid | --border | grid lines |
--chart-label | --muted-foreground | tick labels |
--chart-crosshair | --muted-foreground at 75% | the hover line |
--chart-tooltip-background | --popover | the tooltip panel |
:root {
--chart-grid: var(--muted);
--chart-label: var(--foreground);
}Accessibility
The chart is an image named by ariaLabel ("Waterfall chart" by default). Put the start and end values in ariaDescription, since the bridge between them is hard to follow without seeing it.
- Tab
- Moves focus to the chart and its first step.
- Arrow Right
- Moves to the next step. ArrowDown does the same.
- Arrow Left
- Moves to the previous step. ArrowUp does the same.
- Home
- Jumps to the first step.
- End
- Jumps to the last step.
API reference
Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).
WaterfallChart
datareadonly Record<string, unknown>[]
The steps, left to right: each row's Waterfall dataKey is its signed change; a row whose totalKey field is true is a total (see Waterfall).
- Type
readonly Record<string, unknown>[]
xDataKey?string
The key of each row's category label.
- Default
"label"
aspectRatio?string | number
Aspect ratio of the chart, as "width / height" or a number.
- Type
string | number- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in px.
- Type
Partial<ChartMargin>
barGap?number
Gap between the bars, as a share of each band.
- Default
0.24
animate?boolean
Animate the bars in on mount: each grows from where the one before it ended, left to right.
- Default
true
animationDuration?number
Length of the entrance in milliseconds.
- Default
1100
ariaLabel?string
Accessible name of the chart.
- Default
"Waterfall chart"
ariaDescription?string
Longer accessible description of the chart.
class?string
Extra class name for the chart container.
style?CSSProperties
Inline styles for the chart container.
children?ReactNode
The chart's parts: Waterfall, Grid, BarXAxis, BarYAxis and ChartTooltip.
status?ChartStatus
"loading" draws a shimmering skeleton shaped like the chart in place of its marks and ignores the pointer; switching to "ready" plays the chart's entrance.
- Default
"ready"
loadingLabel?string
Centered label shown over the plot while status is "loading".
Waterfall
dataKeystring
The key of each row's signed change.
totalKey?string
The key of the field that marks a total row (true), drawn from zero: with a value of its own it sets the running total to it (a starting balance), without one it shows the running total (a subtotal).
- Default
"total"
showTotal?boolean
Append a bar for the final total, labelled totalLabel.
totalLabel?string
The appended total's label.
- Default
"Total"
label?string
The series' name in the tooltip.
positiveFill?string
Fill of the increases.
- Default
"var(--chart-positive)"
negativeFill?string
Fill of the decreases.
- Default
"var(--chart-negative)"
totalFill?string
Fill of the subtotals and the total.
- Default
"var(--chart-1)"
showConnectors?boolean
Draw a dashed step from each bar's end to the next bar.
- Default
true
showValues?boolean
Label each bar with its change (a subtotal with its total).
- Default
true
formatValue?(value: number) => string
Formats a value in the labels and the tooltip. Defaults to a grouped integer, changes with their sign.
- Type
(value: number) => string
radius?number
Corner radius of the bars in px.
- Default
4
fadedOpacity?number
Opacity of the other bars while one is hovered.
- Default
0.3
Grid
horizontal?boolean
Show horizontal grid lines.
- Default
true
vertical?boolean
Show vertical grid lines.
- Default
false
numTicksRows?number
Number of horizontal grid lines. Ignored when rowTickValues is set.
- Default
5
numTicksColumns?number
Number of vertical grid lines.
- Default
10
rowTickValues?number[]
Explicit y values for the horizontal grid lines. Overrides numTicksRows.
stroke?string
Color of the grid lines.
- Default
"var(--chart-grid)"
loadingStroke?string
Grid color while the chart is loading. Falls back to stroke.
strokeOpacity?number
Opacity of the grid lines.
- Default
1
strokeWidth?number
Width of the grid lines in px.
- Default
1
strokeDasharray?string
Dash pattern of the grid lines.
- Default
"4,4"
highlightRowValues?number[]
Y values of horizontal lines drawn with the highlight styling, for example a zero baseline.
highlightRowStroke?string
Color of the highlighted rows.
- Default
"var(--chart-foreground-muted)"
highlightRowStrokeOpacity?number
Opacity of the highlighted rows.
- Default
1
highlightRowStrokeWidth?number
Width of the highlighted rows in px.
- Default
1
highlightRowStrokeDasharray?string
Dash pattern of the highlighted rows.
- Default
"0"
fadeHorizontal?boolean
Fade the horizontal lines toward transparent at the left and right edges.
- Default
true
fadeVertical?boolean
Fade the vertical lines toward transparent at the top and bottom edges.
- Default
false
hideHorizontalEdgeLines?boolean
Drop the first and last horizontal line (kept when two or fewer remain).
- Default
false
hideVerticalEdgeLines?boolean
Drop the first and last vertical line (kept when two or fewer remain).
- Default
false
shimmer?boolean
While the chart is loading, sweep a bright band across the grid.
- Default
false
shimmerStroke?string
Color of the shimmer band.
- Default
"color-mix(in oklch, var(--bkm-foreground) 68%, transparent)"
shimmerSpeed?number
Speed multiplier of the shimmer sweep. 2 is twice as fast.
- Default
1
BarXAxis
tickerHalfWidth?number
Half-width in px of the zone around the date pill inside which tick labels are hidden.
- Default
50
showAllLabels?boolean
Show every category label, even where they overlap, instead of thinning them to maxLabels and to the plot width.
- Default
false
maxLabels?BarLabelCount
Maximum number of category labels when showAllLabels is off. Fewer are shown, evenly spaced, when that many would not fit the plot width. Pass { base, sm, md, lg, xl } to vary it with the chart's width (640, 768, 1024 and 1280 px and up).
- Default
12
BarYAxis
showAllLabels?boolean
Horizontal charts: show every category label instead of thinning to maxLabels.
- Default
true
maxLabels?number
Horizontal charts: maximum number of category labels when showAllLabels is off.
- Default
20
numTicks?number
Vertical charts: target number of value ticks. Grid settings take precedence.
- Default
5
formatLargeNumbers?boolean
Vertical charts: abbreviate values of 1000 and above as thousands, for example 2k.
- Default
true
formatValue?(value: number) => string
Vertical charts: formats a value tick into its label. Overrides formatLargeNumbers.
- Type
(value: number) => string
ChartTooltip
showDatePill?boolean
Show the date pill that rides along the bottom of the plot.
- Default
true
showCrosshair?boolean
Show the vertical crosshair line. Bar charts leave it off unless this is true (the dots and the category pill mark the bar).
- Default
true
showDots?boolean
Show a dot on every series at the hovered position.
- Default
true
dotVariant?"dot" | "ring"
Dot style: a filled "dot" or a transparent "ring" square. Read by BarChart only.
- Type
"dot" | "ring"- Default
"dot"
dotSize?number
Dot radius in px.
- Default
5
dotRadiusFraction?number
Corner radius of the "ring" variant as a fraction of its side (0 is square, 0.5 is a circle). Read by BarChart only.
- Default
0.25
dotScale?number
Multiplier applied to the dot or ring size. Read by BarChart and LiveLineChart.
- Default
1
dotStrokeWidth?number
Stroke width of the dots in px.
- Default
2
indicatorColor?string | ((point: Record<string, unknown>) => string)
Color of the crosshair. Only a string is applied; the function form that bklit-ui accepts is ignored and the default is used.
- Type
string | ((point: Record<string, unknown>) => string)- Default
"var(--chart-crosshair)"
#content?slot: { point, index }
Replaces the default tooltip panel body. Receives the hovered data row and its index; with pinnable, also whether the panel is pinned and a dismiss that unpins it (for a close button in a pinned panel's detail).
pinnable?boolean
A click (or Enter, or Space) on the chart pins the tooltip where it is: the panel takes the pointer, so its content can grow into detail and hold controls, until another click, Escape or dismiss lets it go.
- Default
false
rows?(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]
Replaces the default rows (one per series) with your own list of { color, label, value }.
- Type
(point: Record<string, unknown>) => { readonly color: string; readonly label: string; readonly value: string | number }[]
dotColor?string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)
Fill of the tooltip dots. A function receives the hovered row and the series config, and is called again each time the hovered row changes. Defaults to each series' color; a ProfitLossLine's dot takes the color of the hovered value's sign.
- Type
string | ((point: Record<string, unknown>, line: ChartLineConfig) => string)
#default?slot
Extra content rendered below the rows in the default panel, for example marker details. Without it, a chart with ChartMarkers lists the markers on the hovered date there.
class?string
Extra class name for the tooltip panel.
springConfig?SpringConfig
Spring for the floating panel when matchCrosshair is on. Defaults to the chart's tooltip spring.
matchCrosshair?boolean
Make the floating panel follow the pointer with the same spring as the crosshair instead of damping.
- Default
false
damping?number
Spring damping for the floating panel when matchCrosshair is off, on bklit's 0 to 100 scale: lower is bouncier, higher slower, 0 moves the panel instantly. The default, 20, is the snappy hover spring (stiffness 3600, damping 120); every other value is bklit's spring for it played six times faster.
- Default
20
indicatorDasharray?string
Dash pattern of the crosshair. Omit for a solid line.
indicatorFadeEdges?IndicatorFadeEdges
Vertical fade of the crosshair: both ends, the top, the bottom, or none (solid).
- Default
"both"
indicatorFadeLength?number
Size of the crosshair's fade, as a percentage of its height (2 to 40).
- Default
10
indicatorEndColor?string
Bottom colour of the crosshair: it ramps from indicatorColor at the top to this at the bottom (composes with the fade).
indicatorEnd?"plot" | "point"
How far down the crosshair reaches: the whole plot, or down to the hovered point of the first series.
- Type
"plot" | "point"- Default
"plot"
dotHaloBlur?number
Blur in px on the dots' halo, for a soft glow.
- Default
0
topOffset?number
Extra gap in px between the top of the plot and the tooltip panel.
- Default
0
dateLabels?readonly string[]
The date pill's text for each data row, in row order (pair it with XAxis labels).
boxSpringConfig?SpringConfig
Spring for the floating panel. Takes priority over matchCrosshair and damping.
indicatorWidth?IndicatorWidth
Thickness of the crosshair: a width in px, or "line" (1px), "thin" (2px), "medium" (4px) or "thick" (8px).
- Default
"line"
WaterfallChartLoading
margin?Partial<ChartMargin>
Space around the plot in px. Missing sides use the chart's default.
- Type
Partial<ChartMargin>
aspectRatio?string | number
Aspect ratio of the placeholder, as "width / height" or a number.
- Type
string | number- Default
the chart's
label?string
Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.
loadingLabel?string
Deprecated: Use label, the name every chart's placeholder takes..
class?string
Extra class name for the chart container.
Examples
4 examples on Vue, each live with its code and its own install command.
