On this page

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.

Headline numbers and a per-region table
View of Headline numbers and a per-region table
Revenue
$1.58K
Up 4.2%vs last month
Gross margin
34.1%
Down 1.2 ptsvs last month
Cost per job
$212
Up +$8vs last month
Revenue and open jobs by region
RegionRevenue, kOpen jobs
North 4826
South 39114
East 4369
West 26827

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.

slim-bars.css
/* 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.

Sparklines in a KPI row and a table
View of Sparklines in a KPI row and a table

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.

Meters and a share bar
View of Meters and a share bar

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 tone take accent, accent-soft, warn, neutral and gain in turn, and never loss: 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.

Orders against plan, by month
View of Orders against plan, by month

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 #

NameTypeDefaultRequiredDescription
captionReactNode—No

Muted text after the delta, e.g. "vs last week".

classNamestring—No—
deltaReactNode—No

Usually a , shown under the value.

formatFormatSpec'number'No

Default 'number'.

labelReactNode—No

Small muted line above the value.

size'lg' | 'md' | 'sm''lg'No

Default 'lg'.

toneToneinkNo

Color role of the value. Default: ink.

valuenumber | string—Yes

A number formatted with format, or preformatted text.

NameTypeDefaultRequiredDescription
classNamestring—No—
formatFormatSpec'number'No

Default 'number'.

good'up' | 'down''up'No

Which direction is good news; picks the tone when tone isn't set. Default 'up'.

signedbooleanfalseNo

Show the sign on the number. Default false: the arrow carries the direction.

toneTone—No—
valuenumber—Yes

The change, e.g. -1.2 for "▼ 1.2 pts".

NameTypeDefaultRequiredDescription
classNamestring—No—
fillFill'solid'No

Default 'solid'.

formatFormatSpec'number'No

Default 'number'.

labelstring—Yes

Start of the accessible name, e.g. "Margin".

maxnumber—Yes—
minnumber0No

Default 0.

targetnumber—No

Draws a target tick.

toneTone'accent'No

Default 'accent'.

valuenumber—Yes—
widthnumber | string64No

A number is px; a string is any CSS length, e.g. "100%" to fill a table cell. Default 64.

NameTypeDefaultRequiredDescription
classNamestring—No—
countnumber—Yes—
labelReactNode | nullthe formatted countNo

Text after the dots. Default: the formatted count. null hides it (the count stays readable).

maxnumber30No

Most dots drawn; the label still shows the full count. Default 30.

perRownumber15No

Dots per row. Default 15.

toneTone'accent'No

Default 'accent'.

NameTypeDefaultRequiredDescription
areabooleanfalseNo

Fills under the line. Default false.

classNamestring—No—
domainreadonly [number, number]the extent of the values and the targetNo

Default the extent of the values and the target. The first value is the bottom edge and the second the top, so [10, 1] puts 1 at the top, as on Chart. Values outside it are clamped.

endpointbooleanfalseNo

A dot on the last valid value. Default false. At the right edge the dot overhangs the box by about 6 px, so an overflow: hidden ancestor can clip it.

heightnumber28No

Height in px. Default 28.

labelstring—Yes

Accessible name, e.g. "Clicks, last 28 days".

targetnumber—No

Draws a thin rule at this value. Outside an explicit domain it isn't drawn, with a warning.

toneTone'accent'No

Default 'accent'.

valuesreadonly (number | null)[]—Yes

One value per step, left to right. A null or non-finite value breaks the line.

Meters #

NameTypeDefaultRequiredDescription
classNamestring—No—
fillFill'solid'No

Default 'solid'.

formatFormatSpec'number'No

Default 'number'.

labelstring—Yes

Accessible name.

maxnumber100No

Default 100.

minnumber0No

Default 0.

minLabelReactNode | nullthe formatted `min`No

Text under the start. Default: the formatted min. null hides it.

targetnumber—No

Draws a tick and, by default, a "Target …" label.

targetLabelReactNode | null"Target <formatted target>"No

Text under the target tick. Default "Target ". null hides it.

toneTone'accent'No

Default 'accent'.

valuenumber—Yes—
NameTypeDefaultRequiredDescription
classNamestring—No—
formatFormatSpec'number'No

Default 'number'.

labelstring—Yes

Start of the accessible name, e.g. "Margin".

maxnumber100No

Default 100.

minnumber0No

Default 0.

referencenumber—Yes

The planned or estimated value: an empty ring.

referenceLabelReactNodethe formatted referenceNo

Text above the ring. Default: the formatted reference.

referenceToneTone'neutral'No

Ring color. Default 'neutral'.

showScalebooleantrueNo

Min and max labels under the track. Default true.

toneTone'accent'No

Dot, gap and value label color. Default 'accent'.

valuenumber—Yes

The actual value: a filled dot.

valueLabelReactNodethe formatted valueNo

Text above the dot. Default: the formatted value.

NameTypeDefaultRequiredDescription
classNamestring—No

Extra class on the root element.

formatFormatSpec'number'No

Default 'number'.

labelstring—Yes

Accessible name.

maxnumber—Yes

The end of the range; must be greater than min.

maxLabelReactNode | nullthe formatted `max`No

Text under the end, e.g. "6 s+". Default: the formatted max. null hides it.

minnumber0No

Default 0.

minLabelReactNode | nullthe formatted `min`No

Text under the start. Default: the formatted min. null hides it.

ticksbooleantrueNo

Labels under the track at min, every break and max. Default true.

valuenumber—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.

zonesZoneMeterZones—Yes

A thresholds() result, or its { bins, inclusive }: the breaks, tones and labels of the zones.

NameTypeDefaultRequiredDescription
classNamestring—No—
formatFormatSpec'number'No

Default 'number'.

labelstring—Yes

Accessible name.

legendbooleantrueNo

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%").

segmentsreadonly ShareSegment[]—Yes—
totalnumberthe sum of the segmentsNo

The whole. Default: the sum of the segments. A larger total leaves an empty track.

Legend and tooltip #

NameTypeDefaultRequiredDescription
classNamestring—No—
itemsreadonly LegendItem[]—Yes—
shapeLegendShape—No—
NameTypeDefaultRequiredDescription
classNamestring—No—
segmentsreadonly TooltipSegment[]—Yes—