On this page

Charts

LineChart

Trends over time with a clear line between what happened and what is expected. Actual values are solid, a forecast is dashed, and a target stays on the chart.

When to use it #

Use LineChart for a handful of series that share an x axis: revenue against plan, a forecast that continues the actuals, a scenario next to the current path. For a single value per period, BarChart usually reads faster.

Import #

Terminal
npm i tally-charts
app/revenue.tsx
import { LineChart } from 'tally-charts'
import 'tally-charts/theme.css'

Examples #

Monthly revenue, actual and forecast
View of Monthly revenue, actual and forecast
Monthly revenue, actual and forecast
MonthActualForecast
Jan$410no value
Feb$455no value
Mar$498no value
Apr$530no value
May$590no value
Jun$640$640
Julno value$700
Augno value$745
Sepno value$790
Octno value$850

underlay takes marks that sit under the lines, such as an <Area> on a time axis. The chart draws in a fixed order: the grid first, then the underlay, then the target and band, then the series, then the axes, and last your children. So an underlay is above the grid and under every line, and children stay above the lines. Here last year's orders are a soft area behind this year's line. The underlay is a plain element, so every prop of this chart is still serializable.

Weekly orders this autumn, over the same weeks last year
View of Weekly orders this autumn, over the same weeks last year

Props #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

bandLineBand<D>—No

A soft band between two values, e.g. the likely range of a forecast.

chartIdstring—No

Prefix for pattern and mask ids. React's useId is only unique within one root, so set this when charts render in several React roots on one page.

childrenReactNode—No—
classNamestring—No—
datareadonly D[]—Yes—
dataTableboolean | DataTableOptionstrueNo

Hidden data table for screen readers: true, false, or { caption, columns } to set its caption and rename column headers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
domainreadonly [number, number]every series, the band and the target, rounded to nice ticksNo

Value domain. Default: every series, the band and the target, rounded to nice ticks; zero isn't forced. The order may be reversed: [10, 1] puts 1 at the top, for positions where 1 is best.

emptyReactNode"No data"No

Rendered instead of the plot when data is an empty array. Default "No data".

forecastFromTimeInput—No

Shade from here to the end, e.g. the first forecast month: a category, or a date on a time axis. The shading starts halfway between it and the x before it.

formatFormatSpec'number'No

Default 'number'.

gridbooleantrueNo

Horizontal grid lines at the value ticks ('all' when yAxis is 'none'). Default true.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

initialWidthnumber640No

Width used for server rendering and the first client render. Default 640.

interactivebooleantrueNo

Default true. With false the chart is static: no points are registered, so it has no tab stop, no keyboard hint, no pointer response and no tooltip (tooltip is ignored), and onSelect and onActiveChange never fire. The title and the data table stay.

keyboardHintstring"Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with `onSelect`No

Instructions read with the chart when it takes keyboard focus. Default: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with onSelect. A custom text is used as is. Set it to translate the text; "" turns it off.

marginPartial<Margin>—No—
onActiveChange(id: Id | null, point: ChartPoint<D> | null) => void—No

Called with the new active id, and its point; point.datum is the row from data.

onSelect(id: Id, point: ChartPoint<D>) => void—No

Called on click, Enter or Space; point.datum is the row from data.

radiusnumber4No

Dot radius in px. Default 4.

seriesreadonly LineSeries<D>[]—Yes—
styleCSSProperties—No—
targetnumber | { value: number; label?: string }—No—
titlestring—No

Accessible name of the chart; also the default caption of the data table.

tooltipChartTooltip<D>trueNo

Tooltip on hover and focus: true for the default pill, or a function that renders the content for a point (point.datum is your row). Default true.

underlayReactNode—No

Marks drawn under the series, above the grid, e.g. an <Area> on a time axis. children stay above the series.

widthnumber—No

Fixed width in px; turns off container measuring.

xAccessor<D, string | number> | (TimeScaleSpec<D> & { field: Accessor<D, TimeInput> })—Yes

The x of each row. An accessor puts categories on a point scale: each value appears once, repeats are skipped, and point ids are the values as strings, so 1 and '1' are the same x. A time scale spec with a field puts dates on a time axis instead: rows are sorted by date, rows with the same epoch ms are repeats, and point ids are ISO strings. A row whose x is not a date (or missing) is skipped and breaks every line and the band after the row before it in data order. On a time axis that row is the one before it in the data, not in date order: with unsorted data the break can fall between two other dates.

xAxisTickSpec | 'none''all'No

x axis ticks, or 'none'. Default 'all'.

xAxisFormatAxisFormatthe category itself, or 'auto' dates on a time axisNo

x axis labels; tooltip headers, announcements and the data table's x cells use the same format. Default: the category itself, or 'auto' dates on a time axis.

yAxisTickSpec | 'none''all' (about 5)No

Value axis ticks, or 'none'. The grid follows them. Default 'all' (about 5).

yAxisFormatAxisFormat`format`No

Value axis labels. Default: format.

Keyboard and screen readers #

LineChart is built on Chart, so it follows the same keyboard model as the other charts: it is a single tab stop, and tabbing in shows the first point with its tooltip and announces it. A click that focuses the chart does not. ← and → (and ↑ and ↓) move to the previous or next point, and Home and End jump to the first and last. Enter or Space selects the active point when the chart has onSelect, but only a point that can be selected (a point with selectable: false never promises Enter). Esc clears the active point; it is only consumed when a point is active, so an enclosing dialog still closes.

The widget’s description ends with a keyboard hint (“Use arrow keys to move between points, Home and End for first and last, Escape to clear.”, plus “Press Enter to select.” with onSelect). keyboardHint replaces it, for example to translate it, and keyboardHint="" turns it off.

Screen readers get the chart title and description, then an announcement for each point the keyboard moves to: the position, the x and each series’ value, such as “9 of 9, Dec, 36.0% on the current path, 37.6% with changes”. A visually hidden data table follows the chart with every value, and dataTable renames its caption and headers or turns it off. The underlay is drawing only: it is hidden from assistive technology like the rest of the SVG, so put what it shows in the description or the data, as the example does with last year’s orders.

The full model is in the accessibility guide.