On this page

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.

Before (0.9)
<RankedBars data={causes} label="name" value="amount" />

After:

Cost overruns by cause
View of Cost overruns by cause
Cost overruns by cause
NameAmount
Labor overruns$31.2K
Material waste$18.4K
Rework$12.9K
Equipment rental$7.6K

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: tone is 'accent' (was 'loss') and fill is 'solid' (was 'hatch').
  • Meter: fill is 'solid' (was 'hatch').
  • RangeMeter: tone is 'accent' (was 'loss') and referenceTone is 'neutral' (was 'accent'). The hatched gap stays.
  • DotCount: tone is 'accent' (was 'loss').

To keep the 0.9 look, pass the old values.

Before (0.9)
<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:

After
<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" />
Small pieces with the 0.9 look
View of Small pieces with the 0.9 look

New default colors #

The default palette changed. The roles are the same, the colors are not:

TokenLight, wasLight, nowDark, wasDark, 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.

Before (0.9)
@import 'tally-charts/theme.css';

To keep the old colors, set the four tokens after the theme import:

After
: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;
}
The four tones in the 0.9 colors
View of The four tones in the 0.9 colors

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.

Before (0.9)
<BarChart data={weeks} x="week" y="margin" />

After, with a title:

Margin by week
View of Margin by week

After, with a heading that already names the chart. aria-labelledby points at the id of the heading:

Weekly margin, named by its heading
View of Weekly margin, named by its heading

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> & {…}:

Before (0.9)
interface MyBarsProps<D> extends BarChartProps<D> {
  accent?: boolean
}
After
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.

Before (0.9)
<LineChart data={rows} x={{ type: 'time', field: 'date' }} series={series} />

After:

Orders per week, rows with a bad date dropped
View of Orders per week, rows with a bad date dropped
After, Area
<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.

Before (0.9)
<RunwayChart title="API quotas this week" rows={rows} timeZone="local" />
After
<RunwayChart title="API quotas this week" rows={rows} zone="local" />

A live chart with the new prop:

Checkout API quota this week
View of Checkout API quota this week

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.

Before (0.9)
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.

Orders by region, with your own keyboard hint
View of Orders by region, with your own keyboard hint
After, in a test
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.

Weekly orders this autumn, over the same weeks last year
View of Weekly orders this autumn, over the same weeks last year

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.

Build it once
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)
Orders per month
View of Orders per month

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.

Orders by region, select a bar
View of Orders by region, select a bar

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.
  • y2 on Chart, scale="y2" on Line, Area, Band, Bars, ValueLabel, Target and Axis, and tone on Axis. See Two value axes.
  • position on Target, to place a rule within a category of a band or point scale, and y as a category. See Composition.
  • A reversed y scale, y={{ domain: [10, 1] }}, is now documented behaviour. See Composition.
  • color on ShareBar segments, Legend items and solid Bars, for any CSS colour outside the tones.
  • width on InlineBar takes a string, so width="100%" works. See Small pieces.
  • at="max" and variant="pill" on ValueLabel; valueLabel="max" and valueLabelVariant on BarChart.
  • interactive on LineChart: 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 new xAxisFormat.
  • The type of <LineChart band={…}>, LineRange → LineBand.
  • <Bars tooltip={(d) => segments}> → <Bars segments={(d) => segments}>.
  • <ComparisonBars overIsBad={false}> → <ComparisonBars good="up"> (the default is good="down"); onPlanText → onPlanLabel.
  • useChart('MyMark') → useChart(), which returns only the public fields (chartId, warn, radius, registerPoints and unregisterPoints are gone).
  • useRegisterPoints(ctx, points) → useRegisterPoints(points).
  • ctx.x.scale and ctx.y.scale are the library's own LinearScale, BandScale, PointScale and TimeScale. 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, WaterfallKind and DeltaDirection are no longer exported. Use string literals.
  • tally-charts/core keeps only formatting, thresholds, heatmapLevel, toNumber, toTime and the shared and scale types. createScale, computeBars, categoryTicks and the other layout helpers, createWarner and isDev are 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-columns and --ch-seq-ink-strong became private --_ch-* variables. [data-ch-dir] on bars → [data-ch-direction], as on Delta.
  • Percent and pts axes drop their decimals when every tick is whole: "0%", not "0.0%".
  • Chart (and so every high-level chart) and Heatmap warn in development when title is missing.
Before (0.5)
<LineChart data={rows} x="year" series={series} axis="currency" axisFormat={(v: string | number) => String(v)} />
After (0.6)
<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 use getByRole('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. StripPlot point 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. The ch-tone-text class is gone.
  • Light --ch-warn is #be802f (was #f1a23b) and --ch-neutral #8e8e95 (#a3a3ab); --ch-gain was darkened too, and 1.0 replaced it. Hatched and soft-accent marks have a 1px outline in both themes. Palettes has the old colors as vivid.
  • 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-tone now also sets --ch-seq-base.
  • Heatmap column 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's heatmap-header-total part 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 function tooltip on high-level charts, { preset, digits, signed } formats, axisFormat on BarChart and DotHistogram, chartId on Heatmap, heatmapLevel, and readonly arrays everywhere.
  • 0.6b: keyboardHint on every chart, rowLabel on Heatmap, dataTable={{ caption, columns }} on high-level charts, layout on ComparisonBars, marker and shape: 'band' on Legend items, series on ChartPoint and DotItem, the --ch-heatmap-min-cell token, the parts plot, heatmap-total-row, heatmap-scroll, meter-min-label, range-scale-min and range-scale-max, and the state attributes data-ch-tone-text, data-ch-peak and data-ch-marker.
  • 0.8: ShareBar and ZoneMeter. See Small pieces.
  • 0.9: thresholds(…, { inclusive: 'upper' }), plain { bins, inclusive } zones on ZoneMeter, and selectable on RankedBars, Bars and ChartPoint. See Thresholds.