ChartFrame
The frame buttery's charts are drawn in: gridlines and axis labels, a crosshair or column with a tooltip, keyboard steps, a screen-reader table, and no-data and loading states.
import { ChartFrame } from "@butteryui/react";Demo
When to use it
Use it for
- Combining marks in one chart, such as bars for orders with a line for bags roasted
- Drawing a chart of your own with buttery's axes, hover, keyboard and table, through seriesPath
Not for
- One kind of mark: use LineChart, AreaChart or BarChart
- A trend in a table row or beside a number: use Sparkline
Examples
Orders against last week
This week's orders as bars with last week's as a line over them, two marks in one frame, so each day shows its change.
Orders and bags
A roastery dashboard card: orders as bars and bags roasted as a line in one frame, with a week switch and the busiest day.
Orders and roasting
Busiest day: Sat, 71 orders
Refunds by week
Refunds per week: switching months shows the loading pill, and a month with no refunds yet shows the empty state.
Stock against target
The three sizes, shown on a chart of green coffee on hand against its reorder level.
220px tall
Variants and states
Bars and a line in one frame
Point at a day, or focus the plot and use the arrow keys: the column, the dots and the tooltip move together.
No data and loading
With nothing to draw, a dashed baseline and a caption; while loading, a pill over the same box after 300ms.
No data for this period
Props
ChartFrame
| 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. | |
layout | "point" | "band" | "point" | Where points sit: "point" (the default) or "band", which bars need. |
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". |
data-bt | string | "ChartFrame" | The data-bt stamp, for charts built on the frame. Defaults to "ChartFrame". |
children | ReactNode | The marks: ChartFrame.Line, ChartFrame.Area and ChartFrame.Bars, drawn in order. |
It also takes Omit<ComponentPropsWithRef<"div">, "children">.
ChartFrame.Line
| Prop | Type | Default | Description |
|---|---|---|---|
seriesrequired | string | The key of the series it draws. |
ChartFrame.Area
| Prop | Type | Default | Description |
|---|---|---|---|
seriesrequired | string | The key of the series it draws. |
ChartFrame.Bars
| Prop | Type | Default | Description |
|---|---|---|---|
series | readonly string[] | The keys of the series it draws, side by side in each slot. Defaults to every series. |
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. |
Also exported
| Export | Description |
|---|---|
seriesPath(values: readonly (number | null)[], placement: SeriesPlacement): string | The SVG path buttery draws a series as: smooth through each run of values without ever bending past one,
and open wherever a value is null. Use it to draw a series of your own the way the charts do. |
Accessibility
The plot is one Tab stop, a slider over the points named by the chart's label and described by its summary: Left and Right (or Down and Up) step through the points, Home and End jump to the ends, and each step announces the point's label, its values and the change against the comparison. Escape hides the tooltip. A visually hidden table holds every value. With no data, the box is an image named by the label and the empty message; while loading the pill is a status, outside any busy region so it's read out; announceLoading turns it off when what holds the chart is marked busy.
| Keys | What they do |
|---|---|
| ArrowRight or ArrowUp | Moves to the next point and shows its tooltip, announcing its label, values and change |
| ArrowLeft or ArrowDown | Moves to the previous point |
| Home or End | Jumps to the first or the last point |
| 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, which the no-data and loading states keep. Axis labels stay on one line, the x-axis showing the first and last labels and three more at lg; the tooltip stays inside the frame, and the whole plot is one hit area where pointing anywhere picks the nearest point.