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, so34is34%; 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 byh(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.
| Channel | Conversion |
|---|---|
| 4% | |
| Search | 3% |
| Social | 2% |
| Referral | 6% |
import { BarChart, Stat } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'formatting/presets',
title: 'Presets as strings and as objects',
rscSafe: true,
} satisfies ExampleMeta
const channels = [
{ channel: 'Email', conversion: 4.2 },
{ channel: 'Search', conversion: 3.1 },
{ channel: 'Social', conversion: 1.8 },
{ channel: 'Referral', conversion: 5.6 },
]
// A preset is a string or `{ preset, digits, signed }`. Both are plain values, so this example
// renders in a Server Component, unlike a formatter function.
export default function Presets() {
return (
<div style={{ display: 'grid', gap: '1.5rem' }}>
<div style={{ display: 'flex', flexWrap: 'wrap', gap: '2rem' }}>
<Stat label="Monthly revenue" value={1840000} format="currency-compact" />
<Stat label="Conversion" value={3.9} format="percent" />
<Stat label="Change since March" value={0.6} format={{ preset: 'pts', digits: 1 }} />
<Stat label="Support time" value={126.5} format="hours" />
</div>
<BarChart
data={channels}
x="channel"
y="conversion"
domain={[0, 6]}
format={{ preset: 'percent', digits: 0 }}
height={240}
title="Conversion by channel, whole percents"
description="Referral converts best at 6%, social worst at 2%. Values are rounded to whole percents."
/>
</div>
)
}
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.
'use client'
import { createFormatter, fmt, LineChart } from 'tally-charts'
import { createDateFormatter } from 'tally-charts/core'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'formatting/formatters',
title: 'Euro revenue with formatters built in code',
rscSafe: false,
} satisfies ExampleMeta
const revenue = [
{ date: '2026-01-01', revenue: 12400 },
{ date: '2026-02-01', revenue: 13850 },
{ date: '2026-03-01', revenue: 15200 },
{ date: '2026-04-01', revenue: 14700 },
{ date: '2026-05-01', revenue: 16900 },
{ date: '2026-06-01', revenue: 18350 },
]
// Built once, outside the component. Both take their locale as an option, so they don't need a
// ChartsProvider. The month step makes the date formatter write "Jun 2026", not a full date.
const euros = createFormatter(
{ preset: 'currency', digits: 0 },
{ locale: 'de-DE', currency: 'EUR' },
)
const month = createDateFormatter('month', { locale: 'de-DE', step: 30 * 864e5 })
// Functions can't cross from a Server Component, so this file is a client component.
export default function Formatters() {
return (
<div style={{ display: 'grid', gap: '1.5rem' }}>
<LineChart
data={revenue}
x={{ type: 'time', field: 'date' }}
series={[{ id: 'revenue', label: 'Revenue', value: 'revenue' }]}
format={euros}
xAxisFormat={(tick) => month(Number(tick))}
height={260}
title="Revenue by month, formatted with createFormatter and createDateFormatter"
description="Revenue grew from 12.400 € in January 2026 to 18.350 € in June."
/>
<ul style={{ margin: 0, paddingLeft: '1.25rem' }}>
<li>fmt.currency(18350) is {fmt.currency(18350)}</li>
<li>fmt.currencyCompact(1840000) is {fmt.currencyCompact(1840000)}</li>
<li>fmt.percent(3.9) is {fmt.percent(3.9)}</li>
<li>fmt.pts(0.6) is {fmt.pts(0.6)}</li>
<li>fmt.hours(126.5) is {fmt.hours(126.5)}</li>
<li>euros(18350) is {euros(18350)}</li>
</ul>
</div>
)
}
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 #
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
spec | FormatSpec | 'number' | No | What to write: a preset name ( |
options | FormatOptions | {} | No |
|
Returns Formatter
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
options | LocaleOptions | {} | No | — |
Returns Formatters
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
spec | DateFormatSpec | 'auto' | No | How to write the date: a preset ( |
options | DateFormatOptions | {} | No |
|
Returns DateFormatter