LineChart
Values over time as smooth lines, the comparison in gray beneath, with a crosshair and tooltip that follow the pointer.
import { LineChart } from "@butteryui/react";Demo
When to use it
Use it for
- A value over time, such as daily volume, against the period before
- Two to five series on one scale, such as orders per origin
Not for
- Totals that build up: use AreaChart
- Counts per period or category compared side by side: use BarChart
- A trend in a table row or beside a number: use Sparkline
Examples
Lines and sizes
One line, a line over last week's in gray, or a line per channel in the chart colors, at each of the three sizes.
One series, 220px tall
Loading and empty
A chart's loading and empty states: a pill over its box while a range loads, then a line when there's nothing to draw.
Orders by origin
A dashboard card of orders per origin, with a checkbox per origin that shows or hides its line.
3 of 3 origins
Sales against last period
A week of sales against the week before, in dollars; Tab to the chart, then the arrow keys step through the days.
Variants and states
This period against the last
The previous period is gray and beneath; the tooltip shows the change at each point.
Three series, large
At lg, three more labels show along the bottom once the chart is 640px wide.
Props
LineChart
| 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 |
|---|---|
| Tab | Reaches the plot and shows the tooltip at the latest point, or at the one last stepped to |
| Left or Down arrow | Moves the crosshair and tooltip to the point before |
| Right or Up arrow | Moves the crosshair and tooltip to the point after |
| Home or End | Jumps to the first or last point |
| Escape | Hides the tooltip |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container's width and is 160px tall at size="sm", 220 at "md", the default, and 300 at "lg". The values of its gridlines sit at its end edge; under the plot the first and last labels show, and at "lg" three more once the chart is 640px wide. Axis labels stay on one line. The whole plot is one Tab stop and one pointer target, and the tooltip flips sides at the chart's edge to stay inside it.