On this page

Guides

Formatting

Every chart prop that shows a number takes a format. This page lists the presets, shows how axes and tooltips use them, and covers the functions you call yourself: createFormatter, createFormatters and createDateFormatter.

Presets #

format takes a preset name, a preset with options, or a function of the number. The six presets are:

  • 'currency': the currency in the provider's locale, no decimals by default ($18,350).
  • 'currency-compact': the same with a short suffix and three significant digits ($1.84M).
  • 'percent': values are percentage points, so 34 is 34%; one decimal by default.
  • 'pts': percentage points as a difference, always signed (+0.6 pts).
  • 'number': a plain localized number with at most one decimal. This is the default.
  • 'hours': a number followed by h (126.5 h).

The object form { preset: 'percent', digits: 0, signed: true } sets the fraction digits and whether positive values show a +. A function gets the number and returns the text, and replaces the preset altogether.

The 'pts' and 'hours' presets keep their English suffix ( pts, h) in every locale, and ChartsProvider messages do not change it, because a preset has no access to the provider. Pass a custom format function when you need the unit in another language.

Presets as strings and as objects
View of Presets as strings and as objects
Monthly revenue
$1.84M
Conversion
3.9%
Change since March
+0.6 pts
Support time
126.5 h
Conversion by channel, whole percents
ChannelConversion
Email4%
Search3%
Social2%
Referral6%

Presets and objects are plain values, so this example renders in a Server Component. Locale and currency come from the nearest ChartsProvider, en-US and USD without one; see Hooks and providers.

Axes #

Axes take the same presets and objects, a date format on a time axis, or a function of the tick. The tick is an AxisValue: a number on a value axis, the category on a category axis and a Date on a time axis. When every tick on an axis is a whole number, 'percent' and 'pts' drop their decimals (0%, not 0.0%).

axis and axisFormat mean the only axis of a chart. LineChart has two, so it takes xAxis and yAxis for the ticks and xAxisFormat and yAxisFormat for the labels; the value axis follows format unless yAxisFormat is set. A category axis (the axisFormat of BarChart) takes only a function of the category: a preset or a date format there is ignored, with a warning.

Formatters in code #

createFormatter(spec, options) builds the function a preset stands for. Use it when you need the text yourself or a locale that differs from the provider's. createDateFormatter does the same for dates, from epoch milliseconds to a string, in 'day', 'month', 'quarter', 'year', 'auto' or any Intl.DateTimeFormatOptions. Build both once, outside the component.

Euro revenue with formatters built in code
View of Euro revenue with formatters built in code

A formatter is a function, and a function can not be passed from a Server Component to a client one. A file that gives one to a chart starts with 'use client'; a file that uses only string and object presets does not need it.

fmt and createFormatters #

createFormatters(options) returns one formatter per preset: currency, currencyCompact, percent, pts, number and hours. fmt is createFormatters() with the default locale en-US and the currency USD, ready to use: fmt.currency(18350) is $18,350. For another locale make your own set with createFormatters({ locale: 'de-DE', currency: 'EUR' }). Inside a chart, useFormat() gives you the set for the provider's locale.

createFormatters and createDateFormatter are exported from tally-charts/core only, which has no React in it. createFormatter and fmt come from both tally-charts and tally-charts/core.

import { fmt } from 'tally-charts'
import { createDateFormatter, createFormatters } from 'tally-charts/core'

fmt.percent(34) // "34.0%"

const de = createFormatters({ locale: 'de-DE', currency: 'EUR' })
de.currency(18350) // "18.350 €"

createDateFormatter('month', { locale: 'de-DE' })(Date.UTC(2026, 5, 1)) // "Juni 2026"

Parameters #

ParameterTypeDefaultRequiredDescription
specFormatSpec'number'No

What to write: a preset name ('currency', 'currency-compact', 'percent', 'pts', 'number', 'hours'), an object with preset, digits and signed, or a function, which is returned as is. Default: 'number'.

optionsFormatOptions{}No

locale (default en-US), currency (default USD) and signed, which shows a plus sign for positive values and wins over the spec.

Returns Formatter

ParameterTypeDefaultRequiredDescription
optionsLocaleOptions{}No—

Returns Formatters

ParameterTypeDefaultRequiredDescription
specDateFormatSpec'auto'No

How to write the date: a preset ('day', 'month', 'quarter', 'year'), 'auto' or any Intl.DateTimeFormatOptions. Default: 'auto'.

optionsDateFormatOptions{}No

locale (default en-US), zone (default 'utc') and step, the typical distance between the dates in ms (default: one day). With 'auto' the step picks the fields that tell the dates apart: the time under a day, the day under four weeks, the month under a year, else the year.

Returns DateFormatter