Skip to content
TrademarkTrademark
Docs
Data

States and interaction

Updated: November 12, 2026
View on GitHub

Request states

Charts fetch nothing themselves, so the states of a request are props you set from wherever the data comes from. Handled, a chart becomes a readable panel instead of an empty frame, and it keeps its height, so the page doesn't jump when the data lands.

Type
Default
loading
Draws a loading state in place of the plot. The title and description stay.
booleanfalse
error
Draws the error state in place of the plot.
booleanfalse
errorState
What the error state says. Say what failed and what to do.
ReactNode—
emptyState
What to show when data is empty, or when the date range leaves no rows.
ReactNode—
loading
emptyState
No orders in this range yet.
error
Couldn't load orders. Try again in a minute.

An empty array is not an error: the query ran and matched nothing. That is why emptyState and errorState are separate. When both loading and error are false and data is empty, the empty state shows.

Tooltip and keyboard

Hovering the plot shows a tooltip with every visible series at that x value, written in the chart's format. A line chart draws a cursor line, a bar chart highlights the band (hover on BarChart paints the whole band).

The plot is also reachable from the keyboard. Tab to it, and:

Key
Does
→ ↓Next point
← ↑Previous point
Home / EndFirst / last point
EscHide the tooltip

A pie moves slice by slice with the arrow keys. tooltip={false} turns the tooltip off and takes the plot out of the tab order, for a chart that is only a picture next to its numbers.

Legend

The legend lists the series with their colours. With two or more series, each entry is a button: pressing it hides or shows that series, and the value axis rescales to what is left. That lets the reader take the big series out to see the small ones.

Type
Default
legend.display
Show the legend. Turn it off for one series, where the title already names it.
booleantrue
legend.position
Where the legend sits on the plot: top-left, top-center, top-right, bottom-left, bottom-center or bottom-right.
stringtop-left
legend.direction
Entries side by side, or stacked (useful next to a pie).
rowcolumn
row

Date range

A time series can carry a date-range picker in its header. Give it a start and an end, which set the first range and filter the rows to it, and turn on selector:

Visits
Visits: data
dateVisits
Jan 20252,600
Feb 20252,550
Mar 20252,900
Apr 20253,100
May 20253,050
Jun 20253,400
Jul 20253,600
Aug 20253,500
Sep 20253,900
Oct 20254,100
Nov 20254,300
Dec 20254,600
01500300045006000Feb 2025Apr 2025Jun 2025Jul 2025Aug 2025Oct 2025Dec 2025
Type
Default
date.start / date.end
The first range. Rows outside it are not drawn. The picker needs both.
Date—
date.selector
Show the range picker in the header.
booleanfalse
date.presets
Quick ranges beside the calendar: { display, granularity }. granularity year offers this and last year, month adds the months, week adds the weeks.
PresetsConfigweek
date.dual
Show two months side by side in the calendar.
booleanfalse
date.min / date.max
The earliest and latest day the reader can pick.
Date—
date.onRangeChange
Called with the picked range. Use it to fetch that range from the server.
(range: DateRange) => void—
date.format
How dates are written: a date-fns pattern.
string—

The chart filters the rows it already has. For a long history, fetch the range instead: keep start and end in state, refetch in onRangeChange, and pass the new rows. onRangeChange is a function, so this chart lives in a client component.

Animation

Charts draw in on mount: lines sweep from the left, bars grow from the baseline. Readers who ask for reduced motion never see it. LineChart takes animation={false} and animationBegin, animationDuration and animationEasing to tune it. For live data, either match animationDuration to the sample interval so updates glide, or turn it off so they snap: see LineChart.

Screen readers

Each chart's plot is a figure (role="figure"), named by its title and a summary written from the data, in the chart's valueFormat and locale:

  • a line or bar chart: "Revenue and Cost, Jan to Dec. Revenue: highest 12,400 in Aug, lowest 3,100 in Feb."
  • a pie: "Share by browser: Chrome 62%, Safari 21%, Firefox 9%."

Inside the card, hidden from sight, the chart also renders its data as a table: the x values as rows, a column per series. A reader who wants the numbers can walk them cell by cell. While a chart loads, fails or is empty, the plot is no figure, and its status is read as it is.

The generated summary states only what is in the data. When the point of the chart is something the numbers don't say on their own, write it:

Type
Default
summary
What a screen reader hears after the title, in place of the generated summary.
stringgenerated
aria-label
The plot's whole name, title included, in place of the title and summary. The hidden table stays.
string—

Colour is never the only cue: each series is named in the legend, the tooltip and the table. Use label so those names are words a reader knows, not rev_q_usd.

Edit this page on GitHub