Building blocks
Small pieces
The small pieces are the numbers and meters around your charts: a headline figure, a progress bar, a count of dots, a legend. They are plain HTML and CSS (Sparkline is the one exception, a single stretched <svg>), they read the same --ch-* tokens as the charts, and you can use them anywhere on a page, in a table cell or a dashboard card, without a Chart around them.
The only two that belong with a chart are Legend, which explains what a chart's colors and shapes mean, and TooltipPill, which is what a Tooltip shows. Numbers are formatted with the locale and currency of the nearest ChartsProvider, see Hooks and providers.
Numbers and table cells #
Stat is a headline number with a label, a change and a caption. Delta is the change: an arrow and the size of the move, colored by whether it is good news (good="down" for cost). InlineBar and DotCount fit in a table cell: a bar against a scale with an optional target tick, and a count drawn as dots.
| Region | Revenue, k | Open jobs |
|---|---|---|
| North | 482 | 6 |
| South | 391 | 14 |
| East | 436 | 9 |
| West | 268 | 27 |
import { Delta, DotCount, InlineBar, Stat } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'small-pieces/kpi-row',
title: 'Headline numbers and a per-region table',
rscSafe: true,
} satisfies ExampleMeta
const regions = [
{ name: 'North', revenue: 482, target: 450, open: 6 },
{ name: 'South', revenue: 391, target: 450, open: 14 },
{ name: 'East', revenue: 436, target: 450, open: 9 },
{ name: 'West', revenue: 268, target: 450, open: 27 },
]
const row = { display: 'flex', flexWrap: 'wrap', gap: '2rem' } as const
const cell = { padding: '0.5rem 0.5rem 0.5rem 0', textAlign: 'left' } as const
const head = { ...cell, color: 'var(--ch-ink-muted)', fontWeight: 'normal' } as const
// None of these pieces draws an <svg>: they are HTML and CSS. Props stay serializable (no
// functions), so the example also renders in a Server Component.
export default function KpiRow() {
return (
<div style={{ display: 'grid', gap: '1.5rem' }}>
<div style={row}>
<Stat
label="Revenue"
value={1577}
format="currency-compact"
delta={<Delta value={4.2} format={{ preset: 'percent', digits: 1 }} />}
caption="vs last month"
/>
<Stat
label="Gross margin"
value={34.1}
format={{ preset: 'percent', digits: 1 }}
delta={<Delta value={-1.2} format={{ preset: 'pts', digits: 1 }} good="up" />}
caption="vs last month"
/>
<Stat
label="Cost per job"
value={212}
format="currency"
size="md"
tone="loss"
delta={<Delta value={8} format="currency" good="down" signed />}
caption="vs last month"
/>
</div>
{/* biome-ignore lint/a11y/useSemanticElements lint/a11y/noNoninteractiveTabindex: a scrollable region must be focusable, or keyboard users cannot scroll it on a narrow screen */}
<div role="region" aria-label="Regions" tabIndex={0} style={{ overflowX: 'auto' }}>
<table style={{ borderCollapse: 'collapse' }}>
<caption style={{ ...head, captionSide: 'top' }}>Revenue and open jobs by region</caption>
<thead>
<tr>
<th style={head} scope="col">
Region
</th>
<th style={head} scope="col">
Revenue, k
</th>
<th style={head} scope="col">
Open jobs
</th>
</tr>
</thead>
<tbody>
{regions.map((r) => (
<tr key={r.name}>
<th style={cell} scope="row">
{r.name}
</th>
<td style={cell}>
<InlineBar
label={`${r.name} revenue`}
value={r.revenue}
max={500}
target={r.target}
width={56}
tone={r.revenue >= r.target ? 'gain' : 'loss'}
/>{' '}
{r.revenue}
</td>
<td style={cell}>
<DotCount
count={r.open}
max={30}
perRow={10}
tone={r.open > 20 ? 'loss' : 'neutral'}
/>
</td>
</tr>
))}
</tbody>
</table>
</div>
</div>
)
}
Every element that carries meaning has text for screen readers. Delta says "Up" or "Down" before the number, InlineBar gets an accessible name from its label, and DotCount keeps the full count readable even when it draws fewer dots than max. None of the props are functions, so this example also renders in a Server Component.
InlineBar is 64 px wide by default. width takes a number (px) or any CSS length, so width="100%" fills a table cell. Height has no prop: it is plain CSS on two public parts, [data-ch-part="inline-bar"] (8 px) and [data-ch-part="meter-track"] (12 px). The theme uses no @layer, so an override needs equal specificity and a later position in the cascade, or a stronger selector such as a class plus the attribute. className lands on the bar itself for InlineBar (<InlineBar className="slim" />, matched by .slim[data-ch-part="inline-bar"]) but on the root for Meter, so there the class is on an ancestor (<Meter className="slim" />, matched by .slim [data-ch-part="meter-track"]). The fill follows the track, and the target tick stays visible.
/* Load this after tally-charts/theme.css */
.slim[data-ch-part="inline-bar"],
.slim [data-ch-part="meter-track"] {
height: 4px;
}Colored text in the small pieces, such as a toned value, mixes the tone with --ch-ink so that it stays readable. --ch-tone-text-mix is the share of the tone in that mix, 55% by default; see Theming.
Sparkline is a line of values for a KPI row or a table cell. It has no axes, no tooltip and no tab stop, and it fills the width of its container at a fixed height (28 px by default). A null breaks the line, area adds a soft fill, target draws a thin rule and endpoint puts a dot on the last value. The dot is an HTML element positioned in percent, so it stays round at any width. It overhangs the box by about 6 px at the right edge, so an overflow: hidden ancestor can clip it. Without domain the scale spans the values and the target, and a flat series sits at mid height. With no value at all, the accessible name becomes label: No data.
import { Delta, Sparkline, Stat } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'small-pieces/sparkline',
title: 'Sparklines in a KPI row and a table',
rscSafe: true,
} satisfies ExampleMeta
const clicks = [212, 240, 228, 265, 301, 288, 320, 344, 331, 372, 398, 421]
const refunds = [14, 12, 15, 11, null, 9, 10, 8, 9, 7, 8, 6]
const regions = [
{ name: 'North', values: [30, 34, 33, 38, 41, 44], tone: 'gain' },
{ name: 'South', values: [52, 49, 47, 41, 40, 36], tone: 'loss' },
{ name: 'East', values: [20, 22, 21, 20, 22, 21], tone: 'neutral' },
] as const
const cell = { padding: '0.5rem 0.5rem 0.5rem 0', textAlign: 'left' } as const
const head = { ...cell, color: 'var(--ch-ink-muted)', fontWeight: 'normal' } as const
// A Sparkline fills the width of its container and never measures it, so give it a box. Props
// stay serializable, so the example also renders in a Server Component.
export default function SparklineExample() {
return (
<div style={{ display: 'grid', gap: '1.5rem' }}>
<div style={{ display: 'flex', flexWrap: 'wrap', gap: '2rem' }}>
<div style={{ width: 200 }}>
<Stat
label="Clicks"
value={421}
delta={<Delta value={12.5} format={{ preset: 'percent', digits: 1 }} />}
/>
<Sparkline
values={clicks}
label="Clicks, last 12 days"
tone="gain"
area
endpoint
height={36}
/>
</div>
<div style={{ width: 200 }}>
<Stat label="Refunds" value={6} tone="loss" />
<Sparkline
values={refunds}
label="Refunds, last 12 days"
tone="loss"
endpoint
target={10}
domain={[0, 16]}
height={36}
/>
</div>
</div>
<table style={{ borderCollapse: 'collapse' }}>
<caption style={{ ...head, captionSide: 'top' }}>Margin by region, last 6 months</caption>
<thead>
<tr>
<th style={head} scope="col">
Region
</th>
<th style={head} scope="col">
Trend
</th>
</tr>
</thead>
<tbody>
{regions.map((r) => (
<tr key={r.name}>
<th style={cell} scope="row">
{r.name}
</th>
<td style={{ ...cell, width: 120 }}>
<Sparkline values={r.values} label={`${r.name} margin`} tone={r.tone} endpoint />
</td>
</tr>
))}
</tbody>
</table>
</div>
)
}
Meters and shares #
Meter shows progress toward a target. RangeMeter puts the actual value and the plan on one track, with a hatched gap between them. ZoneMeter colors the track in zones, here good, needs work and poor, and marks the value. ShareBar splits a whole into parts and lists them underneath.
import { Meter, RangeMeter, ShareBar, ZoneMeter } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'small-pieces/meters',
title: 'Meters and a share bar',
rscSafe: true,
} satisfies ExampleMeta
// The `{ bins, inclusive }` shape of `thresholds()`, written out so it is plain data. Each bin is
// [min, max); the first starts at -Infinity and the last ends at Infinity.
const pageLoad = {
inclusive: 'lower',
bins: [
{ label: 'Good', tone: 'gain', min: Number.NEGATIVE_INFINITY, max: 2.5 },
{ label: 'Needs work', tone: 'warn', min: 2.5, max: 4 },
{ label: 'Poor', tone: 'loss', min: 4, max: Number.POSITIVE_INFINITY },
],
} as const
const stack = { display: 'grid', gap: '1.75rem', maxWidth: '32rem' } as const
// Props stay serializable (no functions, only plain objects), so this example also renders in a
// Server Component.
export default function Meters() {
return (
<div style={stack}>
<Meter
label="Sales target"
value={68}
max={100}
target={80}
format={{ preset: 'percent', digits: 0 }}
/>
<RangeMeter
label="Margin"
value={31}
reference={38}
max={50}
format={{ preset: 'percent', digits: 0 }}
referenceLabel="Plan 38%"
/>
<ZoneMeter
label="Largest contentful paint"
value={3.1}
zones={pageLoad}
max={6}
maxLabel="6 s+"
format={{ preset: 'number', digits: 1 }}
/>
<ShareBar
label="Revenue by channel"
format="currency-compact"
segments={[
{ label: 'Direct', value: 2711, tone: 'accent' },
{ label: 'Partners', value: 1890, tone: 'gain' },
{ label: 'Online', value: 1240, tone: 'warn', fill: 'hatch' },
]}
/>
</div>
)
}
ZoneMeter takes the zones as { bins, inclusive }, which is the shape thresholds() returns, so you can pass its result straight in or write the plain object, as here, when the page is a Server Component. Each meter has a label that becomes its accessible name.
ShareBar draws one bar split by value / total, in the order of segments, with a list of the parts underneath ("2,711 · 46%"). legendValue is 'both', 'value' or 'percent', and legend={false} keeps only the bar. A total larger than the sum of the parts leaves the rest as empty track.
- The percents in the list add up to 100.
- A part that rounds to 0% reads "<1%" and stays visible in the bar as a 3px sliver.
- Segments without a
tonetakeaccent,accent-soft,warn,neutralandgainin turn, and neverloss: coral is only ever chosen explicitly.
color paints a segment, a Legend item or a solid Bars bar with any CSS colour, including var(--x), when a tone is not enough, for example a brand colour. It replaces the tone's paint but not its name: data-ch-tone stays, and forced-colors mode still uses system colours. Contrast in light and dark is up to you, and var(--x) is how a colour follows a theme. On Bars it applies only to fill="solid"; a hatched bar keeps its tone and warns in development, because hatching is drawn from one pattern per tone.
Legend and tooltip #
Legend is a list of swatches next to a chart. Each item picks a tone and a shape (bar, dot, line or band), and a line can be dashed. TooltipPill is the segmented pill inside a Tooltip; the content function returns one for the hovered or focused point. A line swatch takes marker: 'dot' or 'ring' for the points of the series, and a band swatch shows the soft fill of a Band.
'use client'
import {
Axis,
Bars,
Chart,
Grid,
Legend,
Line,
NearestPointer,
ShareBar,
Tooltip,
TooltipPill,
} from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'small-pieces/legend-and-tooltip',
title: 'Orders against plan, by month',
rscSafe: false,
} satisfies ExampleMeta
interface Month {
month: string
orders: number
plan: number
}
const months: Month[] = [
{ month: 'Jan', orders: 420, plan: 400 },
{ month: 'Feb', orders: 385, plan: 410 },
{ month: 'Mar', orders: 460, plan: 430 },
{ month: 'Apr', orders: 510, plan: 450 },
{ month: 'May', orders: 475, plan: 470 },
{ month: 'Jun', orders: 540, plan: 490 },
]
// Traffic by source. The tones stay the semantic default; `color` paints a brand's own color.
// Contrast in light and dark is up to you, and `var(--x)` is how a color follows a theme.
const sources = [
{ label: 'Search', value: 5120, tone: 'accent', color: '#4285f4' },
{ label: 'Social', value: 2380, tone: 'accent-soft', color: '#e1306c' },
{ label: 'Email', value: 1460, tone: 'warn', color: 'var(--ch-gain)' },
{ label: 'Direct', value: 980, tone: 'neutral' },
] as const
// `Tooltip content` is a function, so this file is a client file. Legend and TooltipPill are
// plain HTML: Legend sits beside the chart, TooltipPill is what the tooltip shows.
export default function LegendAndTooltip() {
return (
<div>
<Legend
items={[
{ label: 'Orders', tone: 'accent', shape: 'bar' },
{ label: 'Plan', tone: 'neutral', shape: 'line', dashed: true },
]}
/>
<Chart
data={months}
x={{ type: 'band', field: 'month', padding: 0.35 }}
y={{ field: 'orders', domain: [0, 600] }}
margin={{ left: 36 }}
height={260}
title={meta.title}
description="Orders beat the plan in every month except February, and reached 540 in June."
>
<Grid ticks={4} />
<Bars id="month" tone="accent" fill="hatch-fade" />
<Line y="plan" tone="neutral" dashed dots="none" />
<Axis side="left" ticks={4} />
<Axis side="bottom" />
<NearestPointer axis="x" />
<Tooltip
content={(point) => {
const m = point.datum as Month
const diff = m.orders - m.plan
return (
<TooltipPill
segments={[
{ value: m.month },
{ value: m.orders, label: 'orders' },
{
value: `${diff > 0 ? '+' : ''}${diff}`,
label: 'vs plan',
tone: diff >= 0 ? 'gain' : 'loss',
},
]}
/>
)
}}
/>
</Chart>
<ShareBar label="Visits by source" segments={sources} />
</div>
)
}
content is a function, so this example is a client file. Hover a bar or focus the chart and use the arrow keys to see the pill.
Props #
Numbers #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
caption | ReactNode | — | No | Muted text after the delta, e.g. "vs last week". |
className | string | — | No | — |
delta | ReactNode | — | No | Usually a , shown under the value. |
format | FormatSpec | 'number' | No | Default 'number'. |
label | ReactNode | — | No | Small muted line above the value. |
size | 'lg' | 'md' | 'sm' | 'lg' | No | Default 'lg'. |
tone | Tone | ink | No | Color role of the value. Default: ink. |
value | number | string | — | Yes | A number formatted with |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
format | FormatSpec | 'number' | No | Default 'number'. |
good | 'up' | 'down' | 'up' | No | Which direction is good news; picks the tone when |
signed | boolean | false | No | Show the sign on the number. Default false: the arrow carries the direction. |
tone | Tone | — | No | — |
value | number | — | Yes | The change, e.g. -1.2 for "▼ 1.2 pts". |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
fill | Fill | 'solid' | No | Default 'solid'. |
format | FormatSpec | 'number' | No | Default 'number'. |
label | string | — | Yes | Start of the accessible name, e.g. "Margin". |
max | number | — | Yes | — |
min | number | 0 | No | Default 0. |
target | number | — | No | Draws a target tick. |
tone | Tone | 'accent' | No | Default 'accent'. |
value | number | — | Yes | — |
width | number | string | 64 | No | A number is px; a string is any CSS length, e.g. "100%" to fill a table cell. Default 64. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
count | number | — | Yes | — |
label | ReactNode | null | the formatted count | No | Text after the dots. Default: the formatted count. |
max | number | 30 | No | Most dots drawn; the label still shows the full count. Default 30. |
perRow | number | 15 | No | Dots per row. Default 15. |
tone | Tone | 'accent' | No | Default 'accent'. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
area | boolean | false | No | Fills under the line. Default false. |
className | string | — | No | — |
domain | readonly [number, number] | the extent of the values and the target | No | Default the extent of the values and the target. The first value is the bottom edge and the second the top, so |
endpoint | boolean | false | No | A dot on the last valid value. Default false. At the right edge the dot overhangs the box by about 6 px, so an |
height | number | 28 | No | Height in px. Default 28. |
label | string | — | Yes | Accessible name, e.g. "Clicks, last 28 days". |
target | number | — | No | Draws a thin rule at this value. Outside an explicit |
tone | Tone | 'accent' | No | Default 'accent'. |
values | readonly (number | null)[] | — | Yes | One value per step, left to right. A |
Meters #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
fill | Fill | 'solid' | No | Default 'solid'. |
format | FormatSpec | 'number' | No | Default 'number'. |
label | string | — | Yes | Accessible name. |
max | number | 100 | No | Default 100. |
min | number | 0 | No | Default 0. |
minLabel | ReactNode | null | the formatted `min` | No | Text under the start. Default: the formatted |
target | number | — | No | Draws a tick and, by default, a "Target …" label. |
targetLabel | ReactNode | null | "Target <formatted target>" | No | Text under the target tick. Default "Target ". |
tone | Tone | 'accent' | No | Default 'accent'. |
value | number | — | Yes | — |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
format | FormatSpec | 'number' | No | Default 'number'. |
label | string | — | Yes | Start of the accessible name, e.g. "Margin". |
max | number | 100 | No | Default 100. |
min | number | 0 | No | Default 0. |
reference | number | — | Yes | The planned or estimated value: an empty ring. |
referenceLabel | ReactNode | the formatted reference | No | Text above the ring. Default: the formatted reference. |
referenceTone | Tone | 'neutral' | No | Ring color. Default 'neutral'. |
showScale | boolean | true | No | Min and max labels under the track. Default true. |
tone | Tone | 'accent' | No | Dot, gap and value label color. Default 'accent'. |
value | number | — | Yes | The actual value: a filled dot. |
valueLabel | ReactNode | the formatted value | No | Text above the dot. Default: the formatted value. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | Extra class on the root element. |
format | FormatSpec | 'number' | No | Default 'number'. |
label | string | — | Yes | Accessible name. |
max | number | — | Yes | The end of the range; must be greater than |
maxLabel | ReactNode | null | the formatted `max` | No | Text under the end, e.g. "6 s+". Default: the formatted |
min | number | 0 | No | Default 0. |
minLabel | ReactNode | null | the formatted `min` | No | Text under the start. Default: the formatted |
ticks | boolean | true | No | Labels under the track at min, every break and max. Default true. |
value | number | — | Yes | The measured value. A value outside the range is pinned to its end; a missing or non-finite one shows "No data" and draws no marker. |
zones | ZoneMeterZones | — | Yes | A |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
format | FormatSpec | 'number' | No | Default 'number'. |
label | string | — | Yes | Accessible name. |
legend | boolean | true | No | The list of parts under the bar. Default true. |
legendValue | 'both' | 'value' | 'percent' | 'both' ("2,711 · 46%") | No | What each list row shows on the right. Default 'both' ("2,711 · 46%"). |
segments | readonly ShareSegment[] | — | Yes | — |
total | number | the sum of the segments | No | The whole. Default: the sum of the segments. A larger total leaves an empty track. |
Legend and tooltip #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
items | readonly LegendItem[] | — | Yes | — |
shape | LegendShape | — | No | — |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | — | No | — |
segments | readonly TooltipSegment[] | — | Yes | — |