Guides
Theming
Every color, size and motion setting of a chart is a CSS custom property called --ch-<name>, a token. Import tally-charts/theme.css once and the tokens are defined for the light and the dark theme; change one on any element and every chart below it follows. This page lists the tokens, shows how to aim at a single part of a chart, and explains how to force a theme on part of the page.
Tokens #
The theme tokens change between the light and the dark theme. The values are read from theme.css, so the table is always the shipped one. Default values can be tuned in a minor release, for example to keep a contrast ratio; the names and their meaning are stable.
| Token | Light | Dark |
|---|---|---|
--ch-accent | #24356b | #7f9be6 |
--ch-accent-soft | #a9b6de | #6f80b4 |
--ch-loss | #e8505b | #ff6b74 |
--ch-warn | #be802f | #ffb24d |
--ch-gain | #3a93b8 | #5cc0e6 |
--ch-neutral | #8e8e95 | #7c7c86 |
--ch-ink | #111114 | #f4f4f6 |
--ch-ink-muted | #6b6b73 | #a0a0aa |
--ch-grid | #e4e4e9 | #2a2a31 |
--ch-surface | #fafafa | #121215 |
--ch-tooltip-bg | #ffffff | #1d1d22 |
--ch-tooltip-ink | #111114 | #f4f4f6 |
--ch-tooltip-shadow | 0 1px 2px rgb(0 0 0 / 0.06), 0 6px 20px rgb(0 0 0 / 0.08) | 0 1px 2px rgb(0 0 0 / 0.4), 0 6px 20px rgb(0 0 0 / 0.5) |
--ch-hatch-tint | 0.14 | 0.2 |
The shared tokens have one value for both themes: sizes, hatching, motion and the sequential ramp.
| Token | Light | Dark |
|---|---|---|
--ch-hatch-angle | 45 | 45 |
--ch-hatch-width | 1.5px | 1.5px |
--ch-hatch-gap | 6 | 6 |
--ch-share-gap | 2px | 2px |
--ch-font-numeric | tabular-nums | tabular-nums |
--ch-radius | 3px | 3px |
--ch-duration | 400ms | 400ms |
--ch-ease | cubic-bezier(0.2, 0, 0, 1) | cubic-bezier(0.2, 0, 0, 1) |
--ch-dim-opacity | 0.35 | 0.35 |
--ch-tone-text-mix | 55% | 55% |
Tokens without a default in theme.css #
These tokens are public too, but theme.css does not declare them for every chart, so they are not in the tables above. Set them on any element to change the charts below it.
--ch-zone-marker: the color of theZoneMetermarker.--ch-seq-base: the base color of the sequential ramp. It defaults to--ch-loss.--ch-seq-mix-1,--ch-seq-mix-2,--ch-seq-mix-3,--ch-seq-mix-4and--ch-seq-mix-5: the share of the base color in each level.--ch-seq-1,--ch-seq-2,--ch-seq-3,--ch-seq-4and--ch-seq-5: the five levels, computed from the base and the mixes on every chart, legend and heatmap. Read them, but steer them with the base and the mixes, because overriding them has no effect.--ch-heatmap-cell-height: the height of aHeatmapcell. Default44px.--ch-heatmap-min-cell: the narrowest aHeatmapcolumn gets before the grid scrolls sideways. Default56px.
data-ch-seq-tone="<tone>" on an ancestor picks that tone's base and its shares for the current theme. Heatmap's tone prop sets it for you. The attribute must sit on, or below, the element that sets data-ch-theme, or the ramp is computed in the outer theme.
Overriding tokens #
Tokens are inherited, so a style on a container (or a rule in your own stylesheet) reaches every chart inside it. A token can be set to a color, a number or another token: below, --ch-accent is pointed at --ch-loss, and --ch-radius and --ch-hatch-gap are plain numbers. The chart on the left is untouched.
| Month | Revenue |
|---|---|
| Jan | 118 |
| Feb | 126 |
| Mar | 141 |
| Apr | 137 |
| May | 152 |
| Jun | 164 |
| Month | Revenue |
|---|---|
| Jan | 118 |
| Feb | 126 |
| Mar | 141 |
| Apr | 137 |
| May | 152 |
| Jun | 164 |
import type { CSSProperties } from 'react'
import { BarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'theming/token-overrides',
title: 'Revenue by month, default tokens',
rscSafe: true,
} satisfies ExampleMeta
const months = [
{ month: 'Jan', revenue: 118 },
{ month: 'Feb', revenue: 126 },
{ month: 'Mar', revenue: 141 },
{ month: 'Apr', revenue: 137 },
{ month: 'May', revenue: 152 },
{ month: 'Jun', revenue: 164 },
]
const grid = {
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 16rem), 1fr))',
gap: '1.5rem',
} satisfies CSSProperties
// Tokens are inherited custom properties, so a style on the container reaches every chart
// inside it. Here one token is pointed at another one, and two are plain numbers.
const overrides = {
'--ch-accent': 'var(--ch-loss)',
'--ch-radius': '0',
'--ch-hatch-gap': '4',
} as CSSProperties
// Props stay serializable (no functions): the page is a server component.
export default function TokenOverrides() {
return (
<div style={grid}>
<BarChart
data={months}
x="month"
y="revenue"
height={220}
title={meta.title}
description="Revenue grew from 118k in January to 164k in June, in the default accent color."
/>
<div style={overrides}>
<BarChart
data={months}
x="month"
y="revenue"
height={220}
title="Revenue by month, overridden tokens"
description="The same revenue, drawn with the accent set to the loss color, square corners and tighter hatching."
/>
</div>
</div>
)
}
Colors that follow the theme belong in a token or in var(--ch-*), not in a fixed hex value, or the chart will look wrong in the other theme. The --ch-seq-1 to --ch-seq-5 tokens are computed from --ch-seq-base and the --ch-seq-mix-* tokens, so steer those instead of overriding the computed ones.
Colored text (row and value labels, bridge notes, waffle group labels, pill values) mixes the tone with --ch-ink, so that it stays readable on the surface. --ch-tone-text-mix is the share of the tone in that mix: 55% by default. Raise it for more color, lower it for more contrast.
Parts and state attributes #
To change something a token does not cover, select the part with [data-ch-part="…"], for example tooltip or callout-stem. The part names are stable. The classes ch-* and the --_ch-* variables are private and can change in any release, so never select those.
The state and variant attributes are stable too, names and values:
data-ch-tone: the tone of a mark or a piece (accent,accent-soft,loss,warn,gainorneutral).data-ch-fill: how a mark is filled (solid,hatchorhatch-fade).data-ch-active: set on the mark the pointer or the keyboard is on.data-ch-dimmed: set on the marks that are not the active one.data-ch-direction: the way a bar grows (up,down,leftorright).data-ch-theme:lightordark, set by you on an ancestor.data-ch-palette: the palette, set by you on an ancestor.data-ch-seq-tone: the tone whose ramp a sequential scale uses.data-ch-level: the step (a number) of a mark in a stepped scale, for example a heatmap cell.
/* Stable: a part, a state attribute and tokens. */
[data-ch-part="tooltip"] {
--ch-tooltip-bg: #111;
border-radius: 4px;
}
[data-ch-part="bar"][data-ch-active="true"] {
opacity: 0.9;
}
/* Fragile: a class and a private variable. */
.ch-tooltip {
--_ch-swatch-color: red;
}When there is no part for what you want to change, prefer a token. If neither exists, that is a gap in the public surface and worth an issue, not a reason to reach for a class.
Forcing a theme #
Charts follow prefers-color-scheme until an ancestor sets data-ch-theme="light" or data-ch-theme="dark"; the attribute wins over the system setting, and a nested one wins over an outer one. That makes a dark panel on a light page a single attribute. Give the panel the theme's own --ch-surface and --ch-ink so the box matches the chart.
import type { CSSProperties } from 'react'
import { LineChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'theming/nested-dark',
title: 'Active users, in a dark panel',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', users: 1820 },
{ week: 'W2', users: 1905 },
{ week: 'W3', users: 2010 },
{ week: 'W4', users: 1985 },
{ week: 'W5', users: 2140 },
{ week: 'W6', users: 2260 },
]
// The panel sets the theme for everything inside it; the surface and ink come from the theme's
// own tokens, so the box matches the chart.
const panel = {
background: 'var(--ch-surface)',
color: 'var(--ch-ink)',
padding: '1rem',
borderRadius: 'var(--ch-radius)',
} satisfies CSSProperties
// Props stay serializable (no functions): the page is a server component.
export default function NestedDark() {
return (
<div data-ch-theme="dark" style={panel}>
<LineChart
data={weeks}
x="week"
series={[{ id: 'users', label: 'Active users', value: 'users' }]}
height={220}
title={meta.title}
description="Active users rose from 1,820 in W1 to 2,260 in W6."
/>
</div>
)
}