Reference
Migration to 1.0
This page lists what changes when you move from 0.9 to 1.0. Each breaking change shows the 0.9 code, then a live example of the 1.0 code. The additive changes need no action. For what 1.x keeps stable, see Stability.
Breaking changes #
Six changes can break a build or change what a chart draws. Go through them in order.
RankedBars: solid fill by default #
In the library, solid is an actual value and hatch is a plan or a reference. A bare <RankedBars> now draws solid bars; in 0.9 it drew hatched ones. RankedBars: pass fill="hatch" to keep the old look.
<RankedBars data={causes} label="name" value="amount" />After:
| Name | Amount |
|---|---|
| Labor overruns | $31.2K |
| Material waste | $18.4K |
| Rework | $12.9K |
| Equipment rental | $7.6K |
import { RankedBars } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/ranked-bars-hatch',
title: 'Cost overruns by cause',
rscSafe: true,
} satisfies ExampleMeta
const causes = [
{ name: 'Labor overruns', amount: 31200 },
{ name: 'Material waste', amount: 18400 },
{ name: 'Rework', amount: 12900 },
{ name: 'Equipment rental', amount: 7600 },
]
// 0.9 drew these hatched by default. In 1.0 you ask for it with fill="hatch".
export default function RankedBarsHatch() {
return (
<RankedBars
data={causes}
label="name"
value="amount"
format="currency-compact"
fill="hatch"
title={meta.title}
/>
)
}
Small pieces are never loss-colored by default #
The loss color means loss, and the library only draws it when you ask. Four small pieces were loss-colored or hatched with no props, even when nothing was lost. In 1.0 they use the accent color, and solid is an actual value:
InlineBar:toneis'accent'(was'loss') andfillis'solid'(was'hatch').Meter:fillis'solid'(was'hatch').RangeMeter:toneis'accent'(was'loss') andreferenceToneis'neutral'(was'accent'). The hatched gap stays.DotCount:toneis'accent'(was'loss').
To keep the 0.9 look, pass the old values.
<InlineBar value={12.3} max={40} label="Margin" />
<Meter value={34} min={20} max={45} label="Gross margin" />
<RangeMeter value={12.3} reference={36} max={40} label="Margin" />
<DotCount count={29} />After, with the old look pinned:
<InlineBar value={12.3} max={40} tone="loss" fill="hatch" label="Margin" />
<Meter value={34} min={20} max={45} fill="hatch" label="Gross margin" />
<RangeMeter value={12.3} reference={36} max={40} tone="loss" referenceTone="accent" label="Margin" />
<DotCount count={29} tone="loss" />import { DotCount, InlineBar, Meter, RangeMeter } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/small-pieces-pinned',
title: 'Small pieces with the 0.9 look',
rscSafe: true,
} satisfies ExampleMeta
const stack = { display: 'grid', gap: '1.5rem', maxWidth: '24rem' } as const
// 0.9 drew these in the loss color or hatched with no props. In 1.0 you ask for it.
export default function SmallPiecesPinned() {
return (
<div style={stack}>
<InlineBar value={12.3} max={40} format="percent" tone="loss" fill="hatch" label="Margin" />
<Meter value={34} min={20} max={45} format="percent" fill="hatch" label="Gross margin" />
<RangeMeter
value={12.3}
reference={36}
max={40}
format="percent"
tone="loss"
referenceTone="accent"
label="Margin, actual against estimated"
/>
<DotCount count={29} tone="loss" label="29 jobs" />
</div>
)
}
New default colors #
The default palette changed. The roles are the same, the colors are not:
| Token | Light, was | Light, now | Dark, was | Dark, now |
|---|---|---|---|---|
--ch-accent | #2f6bf0 | #24356b | #4d86ff | #7f9be6 |
--ch-accent-soft | #9dbcf6 | #a9b6de | #5a7cc4 | #6f80b4 |
--ch-loss | #e5368d | #e8505b | #ff4fa0 | #ff6b74 |
--ch-gain | #22a363 | #3a93b8 | #3ccf86 | #5cc0e6 |
Actual values are navy, loss is coral and gain is blue, so loss and gain no longer depend on telling red from green. --ch-warn, --ch-neutral, the ink and the surfaces are unchanged. The vivid palette's --ch-gain is #4fa3c7 (was #23a866). No props change. Screenshots of your charts will differ.
@import 'tally-charts/theme.css';To keep the old colors, set the four tokens after the theme import:
:root,
[data-ch-theme="light"] {
--ch-accent: #2f6bf0;
--ch-accent-soft: #9dbcf6;
--ch-loss: #e5368d;
--ch-gain: #22a363;
}
@media (prefers-color-scheme: dark) {
:root:not([data-ch-theme="light"]) {
--ch-accent: #4d86ff;
--ch-accent-soft: #5a7cc4;
--ch-loss: #ff4fa0;
--ch-gain: #3ccf86;
}
}
[data-ch-theme="dark"] {
--ch-accent: #4d86ff;
--ch-accent-soft: #5a7cc4;
--ch-loss: #ff4fa0;
--ch-gain: #3ccf86;
}import type { CSSProperties } from 'react'
import { BarChart, InlineBar } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/old-colors',
title: 'The four tones in the 0.9 colors',
rscSafe: true,
} satisfies ExampleMeta
// The light values of 0.9, set on a wrapper. In your app set them once, after the theme import.
const oldColors = {
'--ch-accent': '#2f6bf0',
'--ch-accent-soft': '#9dbcf6',
'--ch-loss': '#e5368d',
'--ch-gain': '#22a363',
display: 'grid',
gap: '1.5rem',
maxWidth: '24rem',
} as CSSProperties
const quarters = [
{ q: 'Q1', v: 42 },
{ q: 'Q2', v: 48 },
{ q: 'Q3', v: 53 },
{ q: 'Q4', v: 61 },
]
export default function OldColors() {
return (
<div style={oldColors}>
<BarChart
data={quarters}
x="q"
y="v"
domain={[0, 70]}
height={140}
axis="all"
title="Revenue by quarter, in the 0.9 accent"
/>
<InlineBar value={31} max={40} format="percent" label="Actual (accent)" />
<InlineBar value={36} max={40} format="percent" tone="accent-soft" label="Estimate (soft)" />
<InlineBar value={12.3} max={40} format="percent" tone="loss" label="Loss" />
<InlineBar value={24} max={40} format="percent" tone="gain" label="Gain" />
</div>
)
}
The steps of the sequential levels (Heatmap, RunwayChart) are tuned to the new colors. With the old ones the levels stay readable, but the steps between them are less even.
A chart needs a title or aria-labelledby #
Chart and the 11 high-level charts now require an accessible name in their types: a title, or an aria-labelledby that points at an element naming the chart. A chart with neither is a type error. The development warning stays for calls from JavaScript. With both props, aria-labelledby names the chart and title stays the default caption of the data table.
<BarChart data={weeks} x="week" y="margin" />After, with a title:
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/chart-title',
title: 'Margin by week',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', margin: 31.2 },
{ week: 'W2', margin: 32.8 },
{ week: 'W3', margin: 33.5 },
{ week: 'W4', margin: 32.1 },
]
// A `title` names the chart. Without a title or an aria-labelledby this is a type error in 1.0.
export default function ChartTitle() {
return (
<BarChart
data={weeks}
x="week"
y="margin"
domain={[26, 40]}
format="percent"
height={220}
title={meta.title}
/>
)
}
After, with a heading that already names the chart. aria-labelledby points at the id of the heading:
import { BarChart, type BarChartProps } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/chart-labelledby',
title: 'Weekly margin, named by its heading',
rscSafe: true,
} satisfies ExampleMeta
interface Week {
week: string
margin: number
}
const weeks: Week[] = [
{ week: 'W1', margin: 31.2 },
{ week: 'W2', margin: 32.8 },
{ week: 'W3', margin: 33.5 },
{ week: 'W4', margin: 32.1 },
]
// 0.9 wrote `interface MyBarsProps<D> extends BarChartProps<D>`. In 1.0 the props are a type
// alias, so extend it with `&`.
type MyBarsProps<D> = BarChartProps<D> & {
accent?: boolean
}
function MyBars<D>({ accent, ...props }: MyBarsProps<D>) {
return <BarChart {...props} data-accent={accent ? '' : undefined} />
}
// The heading names the chart: aria-labelledby points at its id (a literal, so it is stable).
export default function ChartLabelledby() {
return (
<>
<h3 id="migration-margin-heading">Weekly margin</h3>
<MyBars
data={weeks}
x="week"
y="margin"
domain={[26, 40]}
format="percent"
height={220}
aria-labelledby="migration-margin-heading"
accent
/>
</>
)
}
ChartProps and every *Props of the 11 charts are now type aliases, an intersection with the new exported type ChartName, not interfaces. So interface … extends BarChartProps<D> no longer compiles. Use type … = BarChartProps<D> & {…}:
interface MyBarsProps<D> extends BarChartProps<D> {
accent?: boolean
}type MyBarsProps<D> = BarChartProps<D> & {
accent?: boolean
}An invalid date breaks the line #
Area and LineChart no longer join the line, band or area across a date that isn’t a date, or across a missing value. They break there, as Line and Band already did: a series with a bad date in the middle draws two segments instead of one. To keep the old joined line, filter the rows before you pass them. The same filter keeps an Area joined; for a missing value, filter out the rows whose value is null or NaN.
<LineChart data={rows} x={{ type: 'time', field: 'date' }} series={series} />After:
import { LineChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/invalid-dates',
title: 'Orders per week, rows with a bad date dropped',
rscSafe: true,
} satisfies ExampleMeta
const rows = [
{ date: '2026-09-07', orders: 1355 },
{ date: '2026-09-14', orders: 1440 },
{ date: 'not a date', orders: 1500 },
{ date: '2026-09-28', orders: 1480 },
{ date: '2026-10-05', orders: 1570 },
]
// 1.0 breaks the line at a row whose date is not a date. Filter such rows first to keep it joined.
// The filter runs where the page renders, so no function reaches the chart's props.
export default function InvalidDates() {
return (
<LineChart
data={rows.filter((r) => !Number.isNaN(new Date(r.date).getTime()))}
x={{ type: 'time', field: 'date' }}
series={[{ id: 'orders', label: 'Orders', value: 'orders' }]}
format="number"
height={220}
title={meta.title}
/>
)
}
<Area data={rows.filter((r) => !Number.isNaN(new Date(r.date).getTime()))} x="date" y="orders" />RunwayChart: timeZone is now zone #
RunwayChart names its zone prop zone, as TimeScaleSpec and DateFormatOptions already do. The values and the default ('utc') are the same. There is no alias: timeZone is a type error in 1.0, and from JavaScript it is ignored, so the chart falls back to UTC. Rename the prop.
<RunwayChart title="API quotas this week" rows={rows} timeZone="local" /><RunwayChart title="API quotas this week" rows={rows} zone="local" />A live chart with the new prop:
import { RunwayChart } from 'tally-charts'
import { runwayForecast } from 'tally-charts/core'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/runway-zone',
title: 'Checkout API quota this week',
rscSafe: true,
} satisfies ExampleMeta
// A fixed "now" and a fixed window, so the forecast is the same on every render. One row and no
// legend keep the chart short enough for its card at every width.
const now = '2026-10-21T08:00:00Z'
const domain = ['2026-10-21T00:00:00Z', '2026-10-28T00:00:00Z'] as const
const rows = [
{
id: 'checkout',
label: 'Checkout API',
...runwayForecast({
used: 0.72,
windowStart: '2026-10-18T00:00Z',
resetAt: '2026-10-25T00:00Z',
now,
}),
},
]
// `zone` (in 0.9: `timeZone`) sets the day boundaries and the dates in the status. 'utc' is the
// default; it is spelled out here to show the prop.
export default function RunwayZone() {
return (
<RunwayChart
title={meta.title}
rows={rows}
domain={domain}
now={now}
cell="6h"
labelWidth={140}
legend={false}
zone="utc"
/>
)
}
Built-in strings are not API #
The wording of the strings the library writes itself, such as the keyboard hint, is not part of the public API and can change in a minor release (see Stability). Pass your own keyboardHint, or another text you control, wherever you need to know the exact words, and use ChartsProvider messages to translate any of them by key. In tests, don’t search by the built-in text: find the chart by its title and role.
expect(screen.getByText('Use arrow keys to move between points, Home and End for first and last, Escape to clear.')).toBeInTheDocument()After: a keyboardHint you pass is used as is, so you can assert on it.
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/keyboard-hint',
title: 'Orders by region, with your own keyboard hint',
rscSafe: true,
} satisfies ExampleMeta
const regions = [
{ region: 'North', orders: 1280 },
{ region: 'South', orders: 940 },
{ region: 'East', orders: 1115 },
{ region: 'West', orders: 1460 },
]
// The built-in wording is not API and can change in a minor release. A text you pass is used as is,
// so tests and translations can rely on it.
export default function KeyboardHint() {
return (
<BarChart
data={regions}
x="region"
y="orders"
format="number"
height={220}
title={meta.title}
keyboardHint="Arrow keys move between regions. Home and End jump to the first and last."
/>
)
}
expect(screen.getByRole('application', { name: 'Orders by region' })).toBeInTheDocument()Additive changes #
These need no action. They are new in 1.0.
underlay in LineChart #
LineChart takes an underlay: an element drawn after the grid and before the lines, for example an Area with last year’s values. See LineChart for the props.
import { Area, LineChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'line-chart/orders-last-year',
title: 'Weekly orders this autumn, over the same weeks last year',
rscSafe: true,
} satisfies ExampleMeta
// One row per Monday: this year's orders, and the same week a year earlier.
const weeks = [
{ at: '2026-08-03', orders: 1210, lastYear: 1100 },
{ at: '2026-08-10', orders: 1260, lastYear: 1130 },
{ at: '2026-08-17', orders: 1190, lastYear: 1090 },
{ at: '2026-08-24', orders: 1320, lastYear: 1180 },
{ at: '2026-08-31', orders: 1380, lastYear: 1215 },
{ at: '2026-09-07', orders: 1355, lastYear: 1200 },
{ at: '2026-09-14', orders: 1440, lastYear: 1260 },
{ at: '2026-09-21', orders: 1510, lastYear: 1300 },
{ at: '2026-09-28', orders: 1480, lastYear: 1285 },
{ at: '2026-10-05', orders: 1570, lastYear: 1340 },
{ at: '2026-10-12', orders: 1640, lastYear: 1385 },
{ at: '2026-10-19', orders: 1695, lastYear: 1420 },
]
// Props stay serializable (no functions): the page is a server component. The `underlay` is a
// plain element, so it crosses the server boundary like any other prop.
export default function OrdersLastYear() {
return (
<LineChart
data={weeks}
x={{ type: 'time', field: 'at' }}
series={[{ id: 'orders', label: 'This year', value: 'orders' }]}
// Drawn after the grid and before the line, so last year sits behind this year.
underlay={<Area data={weeks} x="at" y="lastYear" tone="neutral" />}
domain={[0, 2000]}
format="number"
height={260}
title={meta.title}
description="Orders grew from 1,210 to 1,695 a week, 19% above the same week last year, which reached 1,420."
/>
)
}
createDateFormatter in tally-charts/core #
createDateFormatter(spec, options) builds a function from epoch milliseconds to a string, in 'day', 'month', 'quarter', 'year', 'auto' or any Intl.DateTimeFormatOptions. It is exported from tally-charts/core with three types: DateFormatSpec for the first argument, DateFormatOptions for the second and DateFormatter for the result. See Formatting.
import { createDateFormatter, type DateFormatOptions, type DateFormatSpec, type DateFormatter } from 'tally-charts/core'
const spec: DateFormatSpec = 'month'
const options: DateFormatOptions = { locale: 'en-US' }
const monthName: DateFormatter = createDateFormatter(spec, options)import { LineChart } from 'tally-charts'
import {
createDateFormatter,
type DateFormatOptions,
type DateFormatSpec,
type DateFormatter,
} from 'tally-charts/core'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/date-formatter',
title: 'Orders per month',
rscSafe: true,
} satisfies ExampleMeta
const months = [
{ at: '2026-05-01', orders: 5210 },
{ at: '2026-06-01', orders: 5480 },
{ at: '2026-07-01', orders: 5390 },
{ at: '2026-08-01', orders: 5920 },
{ at: '2026-09-01', orders: 6310 },
]
const spec: DateFormatSpec = 'month'
const options: DateFormatOptions = { locale: 'en-US' }
// Build it once, outside the component. It maps epoch milliseconds to a string.
const monthName: DateFormatter = createDateFormatter(spec, options)
export default function DateFormatterExample() {
return (
<LineChart
data={months}
x={{ type: 'time', field: 'at' }}
series={[{ id: 'orders', label: 'Orders', value: 'orders' }]}
format="number"
height={220}
title={meta.title}
description={`Orders reached 6,310 in ${monthName(Date.UTC(2026, 8, 1))}.`}
/>
)
}
The Enter hint only on selectable points #
The keyboard hint adds “Press Enter to select.” only while the active point can be selected: the chart has onSelect and the point doesn’t have selectable: false. In 0.9 the sentence could promise Enter on a chart where it did nothing. Tab into the chart below and listen; remove onSelect and the sentence is gone.
'use client'
import { useState } from 'react'
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'migration/select-hint',
title: 'Orders by region, select a bar',
rscSafe: false,
} satisfies ExampleMeta
const regions = [
{ region: 'North', orders: 1280 },
{ region: 'South', orders: 940 },
{ region: 'East', orders: 1115 },
{ region: 'West', orders: 1460 },
]
// With onSelect the keyboard hint ends with "Press Enter to select." A point with
// `selectable: false` never promises Enter. Without onSelect the sentence is not there.
export default function SelectHint() {
const [selected, setSelected] = useState<string | null>(null)
return (
<>
<BarChart
data={regions}
x="region"
y="orders"
format="number"
height={220}
title={meta.title}
onSelect={(id) => setSelected(String(id))}
/>
<p aria-live="polite">{selected === null ? 'Nothing selected.' : `Selected: ${selected}`}</p>
</>
)
}
Also new in 1.0 #
ChartsProvider messages: every built-in string in your language, by key. See Translating the built-in text.Sparkline: a line of values for KPI rows and table cells, with no measuring and no effects. See Small pieces.y2onChart,scale="y2"onLine,Area,Band,Bars,ValueLabel,TargetandAxis, andtoneonAxis. See Two value axes.positiononTarget, to place a rule within a category of a band or point scale, andyas a category. See Composition.- A reversed
yscale,y={{ domain: [10, 1] }}, is now documented behaviour. See Composition. coloronShareBarsegments,Legenditems and solidBars, for any CSS colour outside the tones.widthonInlineBartakes a string, sowidth="100%"works. See Small pieces.at="max"andvariant="pill"onValueLabel;valueLabel="max"andvalueLabelVariantonBarChart.interactiveonLineChart:interactive={false}draws a static chart. See LineChart.
Earlier changes (0.6 to 0.9) #
If you come from before 0.9, these changes still apply. The full history is in the CHANGELOG.
Renames in 0.6 #
0.6 froze the public API. Every rename, before → after:
<LineChart axis={…} axisFormat={…}>→<LineChart yAxis={…} yAxisFormat={…}>, plus a newxAxisFormat.- The type of
<LineChart band={…}>,LineRange→LineBand. <Bars tooltip={(d) => segments}>→<Bars segments={(d) => segments}>.<ComparisonBars overIsBad={false}>→<ComparisonBars good="up">(the default isgood="down");onPlanText→onPlanLabel.useChart('MyMark')→useChart(), which returns only the public fields (chartId,warn,radius,registerPointsandunregisterPointsare gone).useRegisterPoints(ctx, points)→useRegisterPoints(points).ctx.x.scaleandctx.y.scaleare the library's ownLinearScale,BandScale,PointScaleandTimeScale. D3-only methods such as.copy()are gone, and d3-scale is no longer a dependency.- Axis format functions get an
AxisValue(string | number | Date):(v: string | number) => string→(v: AxisValue) => string, or drop the annotation. - The types
ComparisonStatus,WaterfallKindandDeltaDirectionare no longer exported. Use string literals. tally-charts/corekeeps only formatting,thresholds,heatmapLevel,toNumber,toTimeand the shared and scale types.createScale,computeBars,categoryTicksand the other layout helpers,createWarnerandisDevare internal now.- CSS: style
[data-ch-part="…"], not classes (.ch-pill-seg→[data-ch-part="pill-segment"],.ch-swatch→[data-ch-part="legend-swatch"], …).--ch-swatch-color,--ch-range-ref-color,--ch-heatmap-columnsand--ch-seq-ink-strongbecame private--_ch-*variables.[data-ch-dir]on bars →[data-ch-direction], as onDelta. - Percent and pts axes drop their decimals when every tick is whole: "0%", not "0.0%".
Chart(and so every high-level chart) andHeatmapwarn in development whentitleis missing.
<LineChart data={rows} x="year" series={series} axis="currency" axisFormat={(v: string | number) => String(v)} /><LineChart data={rows} x="year" series={series} yAxis="currency" yAxisFormat={(v: AxisValue) => String(v)} />Accessibility changes in 0.6b #
These need no code change, but tests and custom styles may notice them:
- The chart's focus, keys and
aria-*moved from the<figure>to the plot inside it ([data-ch-part="plot"],role="application"). Tests that focus or send keys to the figure should usegetByRole('application'). The focus ring is on the plot. - Announcements start with the position: "Jul 6, 37.5%" → "1 of 12, Jul 6, 37.5%", and with the series when there are several.
StripPlotpoint labels no longer repeat the series name. - Data tables head each row with its first cell, read empty values as "no value", and use field names in sentence case ("week" → "Week").
- Toned text (row and value labels, bridge notes, waffle group labels, pill values) mixes the tone with ink, keyed on
data-ch-tone-text. Thech-tone-textclass is gone. - Light
--ch-warnis#be802f(was#f1a23b) and--ch-neutral#8e8e95(#a3a3ab);--ch-gainwas darkened too, and 1.0 replaced it. Hatched and soft-accent marks have a 1px outline in both themes. Palettes has the old colors asvivid. - The sequential levels have new shares per tone and theme, and the dark top level is the pure base with dark text.
data-ch-seq-tonenow also sets--ch-seq-base. Heatmapcolumn headers hold only the names. The column totals are a row of their own ([data-ch-part="heatmap-total-row"]), ending with the grand total, so 0.6'sheatmap-header-totalpart is gone. The grid sits in[data-ch-part="heatmap-scroll"].WaffleColumns' default top margin is 44px when it pins the peak pill (8px before), so the pill no longer sits on the tallest column.- An axis keeps only its first label when even its first and last would overlap. Every value stays reachable through the tooltip and the data table.
Additions in 0.6 to 0.9 #
Nothing was removed in 0.8 and 0.9, they only added to the API.
- 0.6: time scales,
ChartPoint<D>in callbacks, a functiontooltipon high-level charts,{ preset, digits, signed }formats,axisFormatonBarChartandDotHistogram,chartIdonHeatmap,heatmapLevel, and readonly arrays everywhere. - 0.6b:
keyboardHinton every chart,rowLabelonHeatmap,dataTable={{ caption, columns }}on high-level charts,layoutonComparisonBars,markerandshape: 'band'onLegenditems,seriesonChartPointandDotItem, the--ch-heatmap-min-celltoken, the partsplot,heatmap-total-row,heatmap-scroll,meter-min-label,range-scale-minandrange-scale-max, and the state attributesdata-ch-tone-text,data-ch-peakanddata-ch-marker. - 0.8:
ShareBarandZoneMeter. See Small pieces. - 0.9:
thresholds(…, { inclusive: 'upper' }), plain{ bins, inclusive }zones onZoneMeter, andselectableonRankedBars,BarsandChartPoint. See Thresholds.