LineChart
Every example on this page is live, drawn by the library's Storybook, where you can also change its props and see the result.
A line chart for displaying numerical data as a connected series of points. Supports simple Y-value arrays, explicit X,Y pairs and dates, one series or several, with optional axes, grid, dots, labels and a legend.
The chart fills the box it is given and keeps filling it in a widget's preview at any size: the lines stretch, while text, ticks, dots and dashes keep their size.
Import
import { LineChart } from "~lib/charts/line-chart";
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
data | CartesianPoint[] | Record<string, CartesianPoint[]> | Yes | N/A | The points to plot (at least 2), or several named series. See Point Formats below |
axis | { x?: XAxisConfig, y?: YAxisConfig } | No | N/A | Axis display configuration. See Axis Configuration below |
width | number | string | No | 300 | Chart width, in pixels or any CSS length |
height | number | string | No | 300 | Chart height, in pixels or any CSS length |
smooth | boolean | No | false | Draw smooth curves through the points |
dots | boolean | No | false | Mark every point with a dot |
stacked | boolean | No | false | Stack each series on the ones before it |
direction | "horizontal" | "vertical" | No | "horizontal" | "vertical" turns the chart on its side: values run across and categories up the left |
legend | boolean | { position: "top" | "top-left" | "top-right" | "bottom" | "bottom-left" | "bottom-right" } | No | N/A | Name each series, below the chart unless placed. Only shown for two or more series |
dataLabel | (point, index, seriesKey) => ReactNode | No | N/A | A label to show by each point; return null to skip one |
dataIcon | (point, index, seriesKey) => IconName | null | No | N/A | An icon to set above a point's label, or on its own; return null to skip one |
Each series of several is told apart by its dash: solid, dashed, dotted, then dash-dot.
Point Formats
The data prop accepts any of the following CartesianPoint formats:
| Format | Description | Example |
|---|---|---|
number[] | Y values only. X is auto-indexed starting at 0 | [100, 200, 400, 300] |
[number, number][] | Explicit [x, y] tuples | [[10, 100], [20, 200], [30, 400]] |
{ x: number; y: number }[] | Object notation | [{ x: 10, y: 100 }, { x: 20, y: 200 }] |
[Date, number][] | Date on X axis (enables date tick formatting) | [[new Date("2024-01-01"), 120], ...] |
[Date, number, T][] | Date with arbitrary metadata (accessible via dataLabel) | [[new Date("2024-01-01"), 120, { emoji: "☀️" }]] |
Axis Configuration
y configures the value axis and x the category axis, wherever direction puts them.
| Name | Type | Axis | Required | Default | Description |
|---|---|---|---|---|---|
visible | boolean | Both | No | false | Whether to show the axis, its ticks and their labels |
name | string | Both | No | N/A | Label displayed along the axis (requires visible: true) |
grid | boolean | Both | No | false | Draw dotted grid lines at the axis's ticks |
min | number | y | No | N/A | Where the value axis starts, instead of the lowest value |
max | number | y | No | N/A | Where the value axis ends, when above the highest value |
type | "date" | x | No | N/A | Treat x values as dates (epoch milliseconds) |
dateFormat | Intl.DateTimeFormatOptions | x | No | N/A | How date ticks are written, instead of the automatic format |
timeZone | string | x | No | N/A | The time zone date ticks fall on whole hours and days of |
Date ticks fall on whole minutes, days, Mondays, months or years, and are labelled at the granularity of their spacing unless dateFormat is given.
Ticks fall on the clock of the time zone in timeZone, and are written in it too, so a chart of a day's prices ticks at midnight, 6, noon and 6 in the place it is about, wherever the frame happens to be drawn. Pass the frame's own zone from useTimeZone(). Without timeZone, the zone in dateFormat.timeZone is used, and without either, the clock of whatever machine draws the widget.
Icons on Points
dataIcon names an Icon for a point, set above its label at a size that reads on its own, so a forecast can show each hour's sky on the line itself rather than in a list beside it. Return null for a point that should have none. The icon and its label move together: above the point, or below it near the top of the chart.
<LineChart
data={hours.map((hour) => [new Date(hour.time), hour.temperature, hour.sky])}
dots
dataLabel={(point) => `${point[1]}°`}
dataIcon={(point) => point[2]}
/>
Examples
Simple Line
A basic line chart with Y values:
Negative Values
The chart auto-scales to accommodate negative values:
With Both Axes
Display X and Y axis lines and tick marks:
X,Y Coordinate Pairs with Axes
Use explicit [x, y] pairs for precise positioning:
Irregular X Spacing
Points do not need to be evenly spaced along the X axis:
With Axis Labels
Use the name property on each axis config to display a label along the axis:
See Also
- BarIndicator - Horizontal bar for displaying ratios
- DonutGauge - Circular gauge for displaying ratios