BarChart
Values per period or category as bars, side by side for each series, with a column that highlights on hover.
import { BarChart } from "@butteryui/react";Demo
When to use it
Use it for
- Counts per period or category: bags roasted per day, orders per origin
- This period's bars beside the last one's
Not for
- Long runs of points, such as a year of days: use LineChart
- Parts of a whole: write the numbers, or use StatTabs for a few states
Examples
Bags per day
Bags roasted each day this week beside last week; pointing at a day, or stepping with the arrow keys, shows the change.
Orders by origin
A dashboard card of orders per origin, one bar per category, with a month switch and the leader written out.
Orders by origin
Ethiopia led with 412 orders
Roast schedule
A chart's loading and empty states: a pill while a week's roasts load, then a line when none are planned yet.
Size and comparison
Bags sold per blend at each size, alone or with last month's bars in gray beside this month's.
220px tall, October only
Variants and states
This week beside last week
Point at a day to highlight its column and read both weeks.
Gains and losses
Bars below zero round at their bottom end.
Props
BarChart
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | Names the chart for screen readers and captions its data table, such as "Sales". | |
summary | string | One line on what the chart shows, read after its name, such as "Up 12% on last week". | |
labelsrequired | readonly string[] | The text for each point along the bottom, such as dates; the first and last show under the plot, and three more at lg. | |
seriesrequired | readonly ChartSeries[] | The series, each with one value per label. | |
size | "sm" | "md" | "lg" | "md" | Its height: "sm" 160, "md" 220 or "lg" 300px. Defaults to "md". |
formatValue | ((value: number) => string) | Writes a value for the tooltip and the table. Defaults to the number with up to two decimals. | |
formatTick | ((value: number) => string) | Writes a gridline's value at the end edge. Defaults to a short form with the decimals its step needs, such as 1.25K. | |
lowerIsBetter | boolean | false | Shows a fall against the comparison as good news (success) and a rise as bad. Defaults to false. |
loading | boolean | false | Shows a LoadingPill over the empty box in place of the plot. Defaults to false. |
loadingLabel | string | "Loading data" | What the loading pill says. Defaults to "Loading data". |
announceLoading | boolean | true | Whether the loading pill's words are read out. Defaults to true; turn it off when what holds the
chart is marked busy, as MetricCard is, so a page of loading charts isn't read out once per chart. |
emptyLabel | string | "No data for this period" | What it says with no values to draw. Defaults to "No data for this period". |
labelsHeading | string | "Date" | Heads the labels' column in the screen-reader table. Defaults to "Date". |
It also takes Omit<ComponentPropsWithRef<"div">, "children">.
ChartSeries
One series of values over a chart's labels.
| Field | Type | Default | Description |
|---|---|---|---|
keyrequired | string | Identifies the series among the chart's others, and marks name it. | |
labelrequired | string | Its name in the tooltip and the screen-reader table, such as "This week". | |
valuesrequired | readonly (number | null)[] | One value per label, in order; null where there isn't one, which leaves a gap. A value that isn't a
finite number, such as NaN, is left out the same way. | |
color | ChartColor | chart-1 | Its color. Defaults to chart-1, chart-2 and on in order, or chart-muted for the comparison. |
comparison | boolean | Marks the series the others are measured against, such as the previous period: it's drawn in
chart-muted under the others, and the tooltip shows the first series' change from it. |
Accessibility
The plot is one Tab stop, a slider over the slots: Left and Right step through them, Home and End jump to the ends, and each step announces the slot's label, values and change. Escape hides the tooltip. A visually hidden table holds every value.
| Keys | What they do |
|---|---|
| ArrowRight or ArrowUp | Moves to the next slot and shows its tooltip, announcing its label, values and change |
| ArrowLeft or ArrowDown | Moves to the previous slot |
| Home or End | Jumps to the first or the last slot |
| Escape | Hides the tooltip |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container's width, and size sets its height: sm 160px, md 220px (the default) or lg 300px. Each label gets an equal slot with its series' bars side by side, 4px apart; axis labels stay on one line, and the whole plot is one hit area where pointing anywhere picks the nearest slot.