On this page

Building blocks

Hooks and providers

BarChart and LineChart read their number formats from a provider, and a mark of your own can do the same. This page covers ChartsProvider, which sets the locale and currency for everything inside it, and the three hooks you need to draw something the library does not: useChart, useFormat and useRegisterPoints.

ChartsProvider #

Put ChartsProvider once near the top of the page. locale is a BCP 47 tag and currency an ISO 4217 code. Every chart, Stat, Meter and axis below it formats numbers, dates and currency that way, so the same data reads naturally for each audience. Without a provider the defaults are en-US and USD.

German locale for every chart on the page
View of German locale for every chart on the page
Revenue in June
18.350 €
Jan to Jun: 91.400 €
Revenue by month, in euros
MonthRevenue
Jan12.400 €
Feb13.850 €
Mar15.200 €
Apr14.700 €
May16.900 €
Jun18.350 €
  • Revenue
  • Cost
Revenue and cost by month, in euros
MonthRevenueCost
Jan12.400 €9.100 €
Feb13.850 €9.600 €
Mar15.200 €10.400 €
Apr14.700 €10.100 €
May16.900 €11.200 €
Jun18.350 €11.900 €

The Stat and both charts share one provider: thousands are separated with a dot, the decimal separator is a comma and the euro sign follows the number. Nothing is passed to the charts except format="currency". The props are plain values, so this example also renders in a Server Component; see Getting started for the charts used here and LineChart for series.

Translating the built-in text #

locale changes numbers and dates; messages changes the words the charts speak on their own: "No data", the keyboard hint, the "1 of 6" position, target text, the column headers of the hidden data table and the default Runway status. Pass an object of plain strings, with {placeholders} where a value goes. Any key you leave out keeps its English default, and a key set to undefined does too. The strings are not functions, so a Server Component can pass them to the provider.

Planned hours by technician, in Polish
View of Planned hours by technician, in Polish

The order of precedence is the prop of one chart (empty, keyboardHint, targetLabel, totalLabel, dataTable.columns), then the provider's messages, then English. A column header taken from a string accessor (y="grossMargin" reads "Gross margin") stays the field name; messages supplies the header only when the accessor is a function or the chart names the column itself. A nested provider without messages inherits its parent's, so <ChartsProvider currency="EUR"> inside a translated provider keeps the translation. One with messages replaces them instead of merging: any key it leaves out goes back to English, not to the parent's text. locale and currency don't inherit: each provider sets its own, with en-US and USD as the defaults.

The provider remembers your object by identity. An inline object, messages={{ noData: '…' }} in a Client Component, is a new object on every render of the parent, so every chart under it renders again. Define the object outside the component or wrap it in useMemo. In a Server Component this does not matter.

The unit suffixes of the pts and hours format presets are not messages; use a custom format function for those units in another language (see Formatting). The wording of the English defaults below is not public API and can change in a minor release; the keys are.

KeyEnglish defaultWhere it is used
noDataNo dataAn empty chart, bar or meter. Also the cell text for a missing heatmap value.
noValueno valueA table cell with nothing in it, read by screen readers next to the dash.
keyboardHintUse arrow keys to move between points, Home and End for first and last, Escape to clear.Read when a chart takes keyboard focus. An empty string removes the hint.
keyboardHintSelectPress Enter to select.Appended to keyboardHint, after one space, when the point can be selected.
position{index} of {total}The live-region position of a point. Placeholders: {index}, {total}.
targettarget {value}A target in a spoken value, such as "40, target 50". Placeholder: {value}.
targetLabelTarget {value}The default text under a Meter's target tick. Placeholder: {value}.
nowNowThe Now line of a RunwayChart.
totalTotalThe total column and row of a Heatmap, and the end row of a WaterfallChart.
headerItemItemA column header of a chart's hidden data table. A header taken from a string accessor keeps the field name.
headerValueValueA data-table column header.
headerCategoryCategoryA data-table column header.
headerDateDateA data-table column header.
headerPeriodPeriodA data-table column header.
headerGroupGroupA data-table column header.
headerRankedDetailsDetailsThe data-table column of a RankedBars meta.
headerColumnColumnA data-table column header.
headerChangeChangeA data-table column header.
headerTotalTotalA data-table column header.
headerPlanPlanA data-table column header.
headerActualActualA data-table column header.
headerDifferenceDifferenceThe ComparisonBars data-table column of plan minus actual.
headerRangeRangeThe data-table column of a LineChart band.
headerRowRowThe row name of a Heatmap that has no label.
headerNameNameA RunwayChart or ScatterChart data-table column header.
headerXXThe name of a ScatterChart x measure that has no xLabel and no field name.
headerYYAs headerX, for y.
headerSizeSizeAs headerX, for size.
headerRunwayDetailDetailThe data-table column of a RunwayChart row's sublabel.
headerRunsOutRuns outA RunwayChart data-table column header.
headerResetsResetsA RunwayChart data-table column header.
headerProjectedAtResetProjected at resetA RunwayChart data-table column header.
headerStatusStatusA RunwayChart data-table column header.
statusDisconnectedDisconnectedDefault status of a RunwayChart row whose source is disconnected.
statusNoForecastNo forecastDefault status of a RunwayChart row without a forecast.
statusRunsOutRuns out {date}Default status line of a RunwayChart row. Placeholder: {date}.
statusAtReset~{percent}% at resetDefault status line when a RunwayChart row does not run out. Placeholder: {percent}.
statusResetsResets {date}Default status line of a RunwayChart row's reset. Placeholder: {date}.
legendProjectedUseProjected useRunwayChart legend.
legendUnderShareunder {shares}%RunwayChart legend, after the shades. Placeholder: {shares}, the level edges as percentages, such as "25, 50, 75, 100".
legendRunsOutRuns outRunwayChart legend.
legendLockedLocked until resetRunwayChart legend.
legendResetResetRunwayChart legend.
legendNoForecastNew window, no forecastRunwayChart legend.
onPlanOn planThe change a ComparisonBars row shows when actual is within the tolerance.
planActual{label}, plan {plan}, actual {actual}, {delta}A ComparisonBars row read aloud. Placeholders: {label}, {plan}, {actual}, {delta}.
waterfallStep{label}, {text}, running total {total}A WaterfallChart step read aloud. Placeholders: {label}, {text}, {total}.
chartRolechartWhat a screen reader calls an interactive chart (aria-roledescription).
runningTotalLabeltotalThe label of the running total in a WaterfallChart tooltip.
peakPeakThe first line of a WaffleColumns callout.
binAllAll valuesThe default Heatmap legend label when there are no breaks.
binUnderUnder {value}The lowest Heatmap legend bin. Placeholder: {value}.
binRange{from} to {to}A middle Heatmap legend bin. Placeholders: {from}, {to}.
binOver{value} and upThe highest Heatmap legend bin. Placeholder: {value}.
valueAgainst{value} against {reference}A RangeMeter's value against its reference, read aloud. Placeholders: {value}, {reference}.
valueAboveabove {max}A ZoneMeter value above its maximum. Placeholder: {max}.
valueBelowbelow {min}A ZoneMeter value below its minimum. Placeholder: {min}.
resetMarkresetThe label next to the reset tick of a RunwayChart row.
heatmapNameHeatmapThe accessible name of a scrolling Heatmap that has no title.
deltaUpUpRead before a Delta's value when it went up.
deltaDownDownRead before a Delta's value when it went down.
deltaFlatNo changeRead before a Delta's value when it did not change.

Custom marks #

When none of the building blocks in Composition draws what you need, write a component and put it inside Chart. useChart() returns the size, the margins, the data, the number formatter, the active point and the x and y scales (narrow them on kind: 'linear', 'band', 'point' or 'time'), y2 when the chart has a second axis it can use (undefined otherwise), useFormat() returns formatters in the provider's locale, and useRegisterPoints() tells the chart where your points are.

Average order value by month, as lollipops
View of Average order value by month, as lollipops

Lollipops are not a built-in mark. Lollipops reads the scales with useChart(), labels each point with a formatter from useFormat(), and registers the points. That registration is what makes NearestPointer find them under the pointer, Tooltip show them and the arrow keys walk them. Focus the chart and press Home to hear the first one.

Several React roots on one page #

Pattern ids, for hatching and gradients, come from React's useId, which is only unique within one root. When charts render in separate roots (islands, micro-frontends), two charts can end up with the same pattern id. Give each chart its own chartId. Chart, the high-level charts and Heatmap take it.

<BarChart chartId="margin-chart" data={weeks} x="week" y="margin" title="Margin by week" />

Props #

NameTypeDefaultRequiredDescription
childrenReactNode—No—
currencystring—No—
localestring—No—
messagesPartial<ChartMessages>—No

Built-in text such as "No data" or the keyboard hint, in your language. Keys left out keep their English default. A nested provider without this prop inherits its parent's messages; one with it replaces them, and any key it leaves out goes back to English, not to the parent's text. Memoised by object identity, so an inline object re-renders every chart under it on each render of the parent: hoist it or wrap it in useMemo. A per-chart prop (empty, keyboardHint, targetLabel, totalLabel) wins over these.

useChart has no parameters.

Returns ChartContextValue

useFormat has no parameters.

Returns UseFormatResult

ParameterTypeDefaultRequiredDescription
pointsreadonly ChartPoint[]—Yes—

Returns void