Skip to main content
The renderer turns raw values into display text: numbers, dates and currencies, in the chart’s locale. The engine emits raw values; formatting happens here, at paint time.

​
Two locales

Two locales are in play:
  • The parsing locale decides how ambiguous input is read (is 01/02/2024 Jan 2 or Feb 1?). The data’s rows are read in data._metadata.parsingLocale, which defaults to en-GB. Values written inside the spec, such as a date in a highlight predicate or an annotation anchor, are read in config({ parsingLocale }), which defaults to en-US. Set the two to match when the data’s locale differs.
  • The formatting locale decides how output is displayed (separators, month names, currency symbols). Set it with the formattingLocale prop on GraphProvider.
Without formattingLocale, display falls back to the spec’s config({ parsingLocale }).

​
Supported locales

en-GB, en-US, ar, pt-PT.

​
What a locale drives

The resolved locale, formattingLocale ?? config.parsingLocale, reaches two separate layers:
  • Value formatting: numbers, dates and currency symbols in axis labels, tooltips, data labels and headline numbers.
  • UI strings: the renderer’s own phrases, such as the headline’s comparison wording. Translations ship for en-GB, en-US, ar and pt-PT.
Two independent fallbacks apply to the strings. A locale outside the supported set resolves to en-GB as a whole, and within a resolved locale a phrase with no translation falls back to the en-GB wording for that phrase alone.
Dates always render in UTC. A host in UTC+13 reading a timestamp near midnight sees the UTC calendar day, not the local one. Shift timestamps in your data first if you need local days.
The duration value format is always English, whatever the locale.

​
Number formatting

Locale governs separators and symbols. The numberFormat config governs the rest, and can override the locale’s separators when you need to:
​
number | 'auto'
default:"auto"
Fixed decimal places, or 'auto' to choose from the value’s magnitude.
​
'auto' | 'k' | 'm' | 'b' | 'none'
'auto' abbreviates from magnitude (1234567 → 1.23m); 'k', 'm' and 'b' force a unit; 'none' writes the number in full. Applies to tooltips, data labels, legends and headlines. Axis ticks always abbreviate by their own magnitude.
​
string
Overrides the locale’s grouping separator.
​
string
Overrides the locale’s decimal separator.

​
Currencies and dates

Currency and date columns detected during value-format inference are formatted for the active locale without extra configuration: a £1,250 column renders with the right symbol and grouping, and a date axis with the locale’s month names.

​
Formatting a value yourself

createValueFormatter is the formatter the renderer uses, for a custom slot or geom renderer that paints its own text. Give it a value format, a locale and the number-format config, and it returns a function from a value to a string:
A geom renderer reads the valueFormat from its layer or axis rather than writing one by hand, so its text matches the tooltip and the ticks.

​
Related