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

Parsing and display formatting have separate locale settings:
  • data.parsingLocale controls parsing of data rows and values written in the spec, such as dates in highlight predicates or annotation anchors. It defaults to en-US.
  • formattingLocale on GraphProvider controls display formatting, including separators, month names and currency symbols.
For example, 01/02/2024 means January 2 in en-US and February 1 in en-GB. Without formattingLocale, display falls back to data.parsingLocale.

Supported locales

Locales are not all supported equally: formattingLocale takes any BCP-47 tag. Underscores are repaired (fr_FR formats as fr-FR). A tag Intl cannot read (!!, zz) formats as en-GB and reports an INVALID_FORMATTING_LOCALE warning through onWarnings. Dates always use the Gregorian calendar, so a label names the same span as its tick, even for a locale whose own calendar differs (fa-IR, -u-ca-islamic). Parsing locales stay en-GB, en-US, ar and pt-PT.

What a locale drives

The display locale is formattingLocale ?? data.parsingLocale ?? 'en-US'. It controls:
  • Value formatting: numbers, dates and currency symbols in axis labels, tooltips, data labels, headline numbers and the overlay menu’s menu head, in the exact tag given. Abbreviated values and axis ticks keep the k, m and b suffixes in every locale (ticks also take t), straight after the digits (3,60k €), and fold by thousands even where the locale’s own notation would not (ja-JP, en-IN).
  • 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 tag picks the translation for its language and region (pt-Latn-PT reads pt-PT), else the one named by its language alone (ar-SA reads ar), else en-US. Within that translation, a phrase with no wording falls back to the en-GB wording for that phrase alone. Number fields inside the editor controls follow the translation’s locale, not the tag. For a language with no translation, wrap the chart in a provider and pass your wording as i18nOverrides. The renderer takes those overrides, and the provider’s locale when set; a phrase left out keeps the chart’s translation. The provider depends on the renderer:
  • GraphRenderer: IntlProvider from @graphysdk/react, keyed by chart phrase ('graph.headlineMetrics.total'). This entry loads no editor code.
  • EditableGraphRenderer: EditorIntlProvider from @graphysdk/react/editable, keyed by chart or editor phrase ('editor.overlayMenu.fillColor'). dir: 'rtl' lays the overlay menus out right to left. Graphy sets no dir on the page: set the page’s yourself.
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 and quarter always reads Q3 2024, 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, and the locale from useFormattingLocale(), so its text matches the tooltip and the ticks.