Charts
bar-chart
A bar chart, vertical or horizontal, grouped or stacked, always measured from zero, with a tooltip on hover and arrow-key reading.
When to use it
Comparing amounts across categories. Use orientation="horizontal" for long names or a ranking, stacked when the series add up to a total. For change over many points in time use line-chart; for a single number use a stat, not one bar.
See it working
The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Charts page.
Line chart
- Requests
- Errors
| day | Requests | Errors |
|---|---|---|
| Mar 1, 2026 | 120 | 56 |
| Mar 2, 2026 | 180 | 76 |
| Mar 3, 2026 | 150 | 52 |
| Mar 4, 2026 | 210 | 88 |
| Mar 5, 2026 | 260 | 72 |
| Mar 6, 2026 | 240 | 100 |
| Mar 7, 2026 | 300 | 84 |
| Mar 8, 2026 | 280 | 120 |
| Mar 9, 2026 | 340 | 96 |
| Mar 10, 2026 | 390 | 112 |
| Mar 11, 2026 | 370 | 140 |
| Mar 12, 2026 | 430 | 124 |
Area chart, stacked
- Images
- Video
- Audio
| month | Images | Video | Audio |
|---|---|---|---|
| Jan 1, 2026 | 12 | 30 | 6 |
| Feb 1, 2026 | 18 | 42 | 9 |
| Mar 1, 2026 | 22 | 61 | 11 |
| Apr 1, 2026 | 27 | 70 | 16 |
| May 1, 2026 | 35 | 84 | 18 |
Bar chart
- Web
- App
| quarter | Web | App |
|---|---|---|
| Q1 | 320 | 210 |
| Q2 | 410 | 290 |
| Q3 | 380 | 350 |
| Q4 | 460 | 420 |
Donut chart
| source | visits | Share |
|---|---|---|
| Search | 5,200 | 49% |
| Direct | 3,100 | 29% |
| Referral | 1,400 | 13% |
| Social | 900 | 8% |
- Search5,200 · 49%
- Direct3,100 · 29%
- Referral1,400 · 13%
- Social900 · 8%
Heatmap
| day | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 |
|---|---|---|---|---|---|---|---|---|
| Mon | 6 | 11 | 16 | 21 | 26 | 8 | 13 | 18 |
| Tue | 13 | 19 | 25 | 8 | 14 | 20 | 26 | 9 |
| Wed | 20 | 27 | 11 | 18 | 25 | 9 | 16 | 23 |
| Thu | 27 | 12 | 20 | 28 | 13 | 21 | 6 | 14 |
| Fri | 11 | 20 | 6 | 15 | 24 | 10 | 19 | 28 |
Radial progress, sparkline, stat
Signups
1,204
+12%than last week
Add it
npx shadcn@latest add @rivier-ui/bar-chartThe registry is named once in components.json: see Installation.
Example
Import it from @/components/viz/bar-chart.
<BarChart
label="Orders by channel per quarter"
data={[
{ quarter: "Q1", web: 320, app: 210 },
{ quarter: "Q2", web: 410, app: 290 },
{ quarter: "Q3", web: 380, app: 350 },
]}
x="quarter"
series={[
{ key: "web", label: "Web" },
{ key: "app", label: "App" },
]}
showValues
/>What it needs
A client component: it uses state, effects or browser behaviour. Packages: d3-scale.
It imports
Source
The whole file. Once copied it is yours: the registry item holds the same text.
"use client";
/**
* @name bar-chart
* @category viz
* @description A bar chart, vertical or horizontal, grouped or stacked, always measured from zero, with a tooltip on hover and arrow-key reading.
* @when Comparing amounts across categories. Use `orientation="horizontal"` for long names or a ranking, `stacked` when the series add up to a total. For change over many points in time use line-chart; for a single number use a stat, not one bar.
* @example
* <BarChart
* label="Orders by channel per quarter"
* data={[
* { quarter: "Q1", web: 320, app: 210 },
* { quarter: "Q2", web: 410, app: 290 },
* { quarter: "Q3", web: 380, app: 350 },
* ]}
* x="quarter"
* series={[
* { key: "web", label: "Web" },
* { key: "app", label: "App" },
* ]}
* showValues
* />
*/
import { scaleBand, scaleLinear } from "d3-scale";
import { useMemo, useState, type ComponentProps, type KeyboardEvent } from "react";
import { cn } from "@/lib/cn";
import {
axisNumberFormatter,
ChartAxis,
ChartContainer,
ChartGrid,
ChartLegend,
chartSeries,
ChartSvg,
ChartTooltip,
estimateTextWidth,
formatNumber,
readNumber,
type ChartFormat,
type ChartSeries,
} from "@/components/viz/chart";
export type BarChartProps<T extends object> = Omit<ComponentProps<"div">, "children"> &
Omit<ChartFormat, "timeZone"> & {
/** One object per category. */
data: readonly T[];
/** The field that names the category. */
x: keyof T & string;
/** The bars per category, in a fixed order: the first takes the highlight colour. */
series: readonly ChartSeries<T>[];
/** What the chart shows, for assistive technology. */
label: string;
/** Bars standing up ("vertical") or lying along the row ("horizontal"). */
orientation?: "vertical" | "horizontal";
/** Stack the series in one bar per category instead of side by side. */
stacked?: boolean;
/** Print each bar's value at its end (the total, when stacked), where it fits. */
showValues?: boolean;
showGrid?: boolean;
/** Default: shown for two or more series. */
showLegend?: boolean;
/** The name of the category column in the table alternative. Default: the `x` field name. */
xLabel?: string;
/** Width / height of the plot. */
aspect?: number;
/** A fixed plot height in pixels instead of a ratio. */
height?: number;
};
type Bar = { category: number; series: number; value: number; from: number; to: number; outer: boolean };
/** Bars are thin; what the band has left over is air. */
const MAX_THICKNESS = 24;
/** The space in the surface colour between touching bars and between stacked segments. */
const GAP = 2;
/** Rounded bar ends follow the theme's roundness up to 4px, and are square when it is "none". */
const ROUND = "[rx:min(var(--radius),4px)] [ry:min(var(--radius),4px)]";
export function BarChart<T extends object>({
data,
x,
series,
label,
orientation = "vertical",
stacked = false,
showValues = false,
showGrid = true,
showLegend,
xLabel,
aspect,
height,
locale,
formatValue,
className,
...props
}: BarChartProps<T>) {
const [active, setActive] = useState<number | null>(null);
const [keyboard, setKeyboard] = useState(false);
const vertical = orientation === "vertical";
const model = useMemo(() => {
const categories = data.map((row) => String((row as Record<string, unknown>)[x] ?? ""));
const bars: Bar[] = [];
const totals: { high: number; low: number }[] = [];
data.forEach((row, category) => {
let high = 0;
let low = 0;
const start = bars.length;
series.forEach((item, index) => {
const value = readNumber(row, item.key);
if (value === null) return;
if (!stacked) {
bars.push({ category, series: index, value, from: 0, to: value, outer: true });
high = Math.max(high, value);
low = Math.min(low, value);
} else if (value >= 0) {
bars.push({ category, series: index, value, from: high, to: high + value, outer: false });
high += value;
} else {
bars.push({ category, series: index, value, from: low, to: low + value, outer: false });
low += value;
}
});
if (stacked) {
// Only the segment at the far end of a stack gets the rounded end.
const mine = bars.slice(start);
const top = mine.findLast((bar) => bar.value > 0);
const bottom = mine.findLast((bar) => bar.value < 0);
if (top) top.outer = true;
if (bottom) bottom.outer = true;
}
totals.push({ high, low });
});
// The baseline is zero, always: a bar is read by its length.
const high = Math.max(0, ...totals.map((total) => total.high));
const low = Math.min(0, ...totals.map((total) => total.low));
return { categories, bars, totals, high, low };
}, [data, x, series, stacked]);
const { categories, bars, totals } = model;
const value = formatValue ?? ((number: number) => formatNumber(number, locale));
const table = {
caption: label,
columns: [xLabel ?? x, ...series.map((item) => item.label)],
rows: data.map((row, index) => [
categories[index] ?? "",
...series.map((item) => {
const number = readNumber(row, item.key);
return number === null ? "" : value(number);
}),
]),
};
const current = active === null ? undefined : bars[active];
const currentLabel = current ? (series[current.series]?.label ?? "") : "";
const announcement = keyboard && current ? `${categories[current.category] ?? ""}, ${currentLabel}: ${value(current.value)}` : "";
const move = (step: number | "first" | "last"): void => {
if (bars.length === 0) return;
setKeyboard(true);
setActive((index) => {
if (step === "first") return 0;
if (step === "last") return bars.length - 1;
if (index === null) return step > 0 ? 0 : bars.length - 1;
return Math.max(0, Math.min(bars.length - 1, index + step));
});
};
const onKeyDown = (event: KeyboardEvent<SVGSVGElement>): void => {
if (event.key === "ArrowRight" || event.key === "ArrowDown") move(1);
else if (event.key === "ArrowLeft" || event.key === "ArrowUp") move(-1);
else if (event.key === "Home") move("first");
else if (event.key === "End") move("last");
else if (event.key === "Escape") setActive(null);
else return;
event.preventDefault();
};
const legend = showLegend ?? series.length > 1;
return (
<div data-slot="bar-chart" className={cn("flex w-full min-w-0 flex-col gap-3", className)} {...props}>
{legend ? <ChartLegend items={series.map((item, index) => ({ label: item.label, index }))} mark="rect" /> : null}
<ChartContainer aspect={aspect} height={height} table={table} announcement={announcement}>
{(size) => {
if (bars.length === 0) {
return <p className="absolute inset-0 flex items-center justify-center text-sm text-muted-foreground">No data</p>;
}
const ticksWanted = Math.max(2, Math.floor((vertical ? size.height : size.width) / (vertical ? 56 : 90)));
const scale = scaleLinear()
.domain(model.low === model.high ? [0, 1] : [model.low, model.high])
.nice(ticksWanted);
const ticks = scale.ticks(ticksWanted);
const axisValue = formatValue ?? axisNumberFormatter(Math.max(Math.abs(scale.domain()[0] ?? 0), Math.abs(scale.domain()[1] ?? 0)), locale);
const widest = (texts: readonly string[]): number => Math.ceil(Math.max(0, ...texts.map((text) => estimateTextWidth(text))));
const valueRoom = showValues ? widest(bars.map((bar) => value(bar.value))) + 8 : 0;
const hasNegative = model.low < 0;
const left = vertical ? widest(ticks.map(axisValue)) + 10 : Math.min(Math.round(size.width * 0.35), widest(categories) + 10) + (showValues && hasNegative ? valueRoom : 0);
const right = vertical ? 4 : Math.max(12, valueRoom);
const top = vertical ? (showValues ? 22 : 10) : 4;
const bottom = 26;
const nameRoom = vertical ? 0 : Math.min(Math.round(size.width * 0.35), widest(categories) + 10) - 10;
scale.range(vertical ? [size.height - bottom, top] : [left, size.width - right]);
const band = scaleBand<number>()
.domain(categories.map((_, index) => index))
.range(vertical ? [left, size.width - right] : [top, size.height - bottom])
.paddingInner(0.3)
.paddingOuter(0.15);
const slots = stacked ? 1 : series.length;
const thickness = Math.max(1, Math.min(MAX_THICKNESS, (band.bandwidth() - GAP * (slots - 1)) / slots));
const groupStart = (category: number): number => (band(category) ?? 0) + (band.bandwidth() - (slots * thickness + (slots - 1) * GAP)) / 2;
const zero = scale(0);
const shapes = bars.map((bar) => {
const across = groupStart(bar.category) + (stacked ? 0 : bar.series * (thickness + GAP));
let a = scale(bar.from);
const b = scale(bar.to);
// Stacked segments keep a gap in the surface colour between them, taken from the end nearer the baseline.
if (bar.from !== 0 && Math.abs(b - a) > GAP + 1) a += Math.sign(b - a) * GAP;
return { bar, across, a, b, tip: b, middle: across + thickness / 2 };
});
const rect = (across: number, a: number, b: number): { x: number; y: number; width: number; height: number } =>
vertical ? { x: across, y: Math.min(a, b), width: thickness, height: Math.abs(b - a) } : { x: Math.min(a, b), y: across, width: Math.abs(b - a), height: thickness };
const plotFrom = vertical ? top : left;
const plotTo = vertical ? size.height - bottom : size.width - right;
const names = categories.map((name) => {
if (vertical) return name;
const fits = Math.max(3, Math.floor(nameRoom / (12 * 0.58)));
return name.length > fits ? `${name.slice(0, fits - 1)}…` : name;
});
// Category names that would run into each other are thinned out; every name stays in the table.
const every = vertical ? Math.max(1, Math.ceil((widest(categories) + 8) / band.step())) : 1;
const labels = !showValues
? []
: stacked
? totals.flatMap((total, category) => {
const middle = groupStart(category) + thickness / 2;
const out: { key: string; text: string; at: number; middle: number; positive: boolean }[] = [];
if (total.high > 0 || total.low === 0) out.push({ key: `${category}:high`, text: value(total.high), at: scale(total.high), middle, positive: true });
if (total.low < 0) out.push({ key: `${category}:low`, text: value(total.low), at: scale(total.low), middle, positive: false });
return out;
})
: shapes.map((shape) => ({ key: `${shape.bar.category}:${shape.bar.series}`, text: value(shape.bar.value), at: shape.tip, middle: shape.middle, positive: shape.bar.value >= 0 }));
// A value that does not fit over its bar is not printed: the tooltip and the table carry it.
const labelFits = (text: string): boolean => !vertical || estimateTextWidth(text) <= (stacked ? band.bandwidth() : thickness + GAP) + 6;
const shape = active === null ? undefined : shapes[active];
const tooltipX = shape ? (vertical ? shape.middle : shape.tip) : 0;
const tooltipY = shape ? (vertical ? Math.min(shape.tip, zero) : shape.middle) : 0;
return (
<>
<ChartSvg
label={label}
width={size.width}
height={size.height}
interactive
onKeyDown={onKeyDown}
onPointerLeave={() => setActive(null)}
onFocus={(event) => {
if (event.currentTarget.matches(":focus-visible")) move("first");
}}
onBlur={() => setActive(null)}
>
{showGrid ? <ChartGrid offsets={ticks.map((tick) => scale(tick))} from={vertical ? left : top} to={vertical ? size.width - right : size.height - bottom} vertical={!vertical} /> : null}
{vertical ? (
<>
<ChartAxis side="left" at={left - 8} ticks={ticks.map((tick) => ({ offset: scale(tick), label: axisValue(tick) }))} />
<ChartAxis side="bottom" at={size.height - bottom + 8} ticks={names.flatMap((name, index) => (index % every === 0 ? [{ offset: (band(index) ?? 0) + band.bandwidth() / 2, label: name }] : []))} />
</>
) : (
<>
<ChartAxis side="bottom" at={size.height - bottom + 8} ticks={ticks.map((tick) => ({ offset: scale(tick), label: axisValue(tick) }))} />
<ChartAxis side="left" at={left - 8 - (showValues && hasNegative ? valueRoom : 0)} ticks={names.map((name, index) => ({ offset: (band(index) ?? 0) + band.bandwidth() / 2, label: name }))} />
</>
)}
<g aria-hidden="true">
{shapes.map((item, index) => {
const full = rect(item.across, item.a, item.b);
if (full.width <= 0 || full.height <= 0) return null;
const fill = chartSeries(item.bar.series).fill;
return (
<g key={index} className={cn("transition-opacity duration-instant motion-reduce:transition-none", active !== null && active !== index && "opacity-45")}>
{item.bar.outer ? (
<>
{/* Rounded at the data end, square at the baseline: a rounded bar, with its baseline half squared off. */}
<rect {...full} className={cn(fill, ROUND)} />
<rect {...rect(item.across, item.a, (item.a + item.b) / 2)} className={fill} />
</>
) : (
<rect {...full} className={fill} />
)}
</g>
);
})}
<line
x1={vertical ? left : zero}
x2={vertical ? size.width - right : zero}
y1={vertical ? zero : top}
y2={vertical ? zero : size.height - bottom}
className="stroke-border-strong"
strokeWidth={1}
shapeRendering="crispEdges"
/>
{labels.map((item) =>
labelFits(item.text) ? (
vertical ? (
<text key={item.key} x={item.middle} y={item.at + (item.positive ? -6 : 6)} dy={item.positive ? 0 : "0.7em"} textAnchor="middle" className="fill-foreground tabular-nums">
{item.text}
</text>
) : (
<text key={item.key} x={item.at + (item.positive ? 6 : -6)} y={item.middle} dy="0.32em" textAnchor={item.positive ? "start" : "end"} className="fill-foreground tabular-nums">
{item.text}
</text>
)
) : null,
)}
{/* Hit areas are larger than the bars: the whole column of a grouped bar, the whole band of a stacked segment. */}
{shapes.map((item, index) => {
const along = stacked ? { a: item.a, b: item.b } : { a: plotFrom, b: plotTo };
const start = stacked ? (band(item.bar.category) ?? 0) : item.across - GAP / 2;
const breadth = stacked ? band.bandwidth() : thickness + GAP;
const area = vertical
? { x: start, y: Math.min(along.a, along.b), width: breadth, height: Math.abs(along.b - along.a) }
: { x: Math.min(along.a, along.b), y: start, width: Math.abs(along.b - along.a), height: breadth };
return (
<rect
key={index}
{...area}
fill="transparent"
onPointerEnter={() => {
setKeyboard(false);
setActive(index);
}}
/>
);
})}
</g>
</ChartSvg>
{shape && current ? (
<ChartTooltip
x={tooltipX}
y={tooltipY}
side={tooltipX > size.width / 2 ? "left" : "right"}
title={categories[current.category]}
rows={[{ label: currentLabel, value: value(current.value), index: current.series, mark: "rect" }]}
/>
) : null}
</>
);
}}
</ChartContainer>
</div>
);
}