AreaChart
Values over time as lines with their area filled in faintly, for totals that build up, with a crosshair and tooltip.
import { AreaChart } from "@butteryui/react";Demo
When to use it
Use it for
- Totals that build up over time, such as subscription revenue
- One or two series, where the fill helps read how much
Not for
- Several series that cross: use LineChart, whose lines don't cover each other
- Counts per period or category: use BarChart
Examples
Revenue panel
A revenue panel: the period switch changes both the total and the chart under it.
$34,950
Total for the quarter
Revenue while loading
Revenue that refreshes on request: a pill shows in the chart's box until the new values arrive.
Updated an hour ago
Sizes
The three sizes on a chart of wholesale revenue, each for where it fits: a card, a page section or a report.
220px tall, the default, for a section of a page
Subscription revenue
Monthly subscription revenue as a filled area, with last year's as a gray line, so each month shows its change.
Variants and states
A total that builds up
Against last year
The comparison is a gray line with no fill.
Props
AreaChart
| 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 points: Left and Right step through them, Home and End jump to the ends, and each step announces the point'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 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. Axis labels stay on one line, the x-axis showing the first and last labels and three more at lg, and the whole plot is one hit area where pointing anywhere picks the nearest point.
Related
See it in the roastery demo's subscriptions.