On this page

Building blocks

Composition

Every chart in tally-charts is a Chart with marks inside it. BarChart, LineChart and the rest are ready-made arrangements of the same 18 building blocks, so when none of them fits, you arrange the blocks yourself.

Chart owns the data, the x and y scales, the size, the keyboard and pointer handling and the accessible name. The building blocks are its children: each one reads the scales from context and draws one thing, or adds one behavior. Order is paint order, so what comes first sits at the back.

Bars, axes and annotations #

Start with a band scale on x and a linear scale on y. Grid and Axis frame the plot, Bars draws the data, and ValueLabel, Target, ColumnHighlight and Callout say what to look at. Tooltip shows the hovered or focused bar.

Gross margin by week, against a 40% target
View of Gross margin by week, against a 40% target

ColumnHighlight and Target come before Bars so they sit behind it. Callout pins a pill to a point by id, so Bars is given id="week" and the callout points at "W5". All the props here are strings, numbers and plain objects, which is why this example also renders in a Server Component.

A high-level chart renders its children after its own marks, so a building block you pass sits on top of the chart. A Callout lives in the HTML overlay: it appears after mount, is hidden from screen readers (put the same facts in the title, the description or the data), and never gets wider than the chart, wrapping instead.

Target also works on a band or point scale. Pass the category as x (or y on a horizontal chart) and position, a fraction of the category's step from 0 (start edge) to 1 (end edge); the default 0.5 is the centre. A pass mark of 73 over buckets 10 wide sits at position={0.3} of "70–79". The end of one category and the start of the next are the same pixel, in the middle of the gap between bars. position on a linear or time scale warns and is ignored.

Scores by bucket, with a pass mark at 73
View of Scores by bucket, with a pass mark at 73

Lines, areas and ranges #

A point scale puts categories on a line. Band fills a range between a low and a high field, Area fades down from the line, and Line draws the path. Region shades a span of the x axis, here the forecast months. NearestPointer finds the point closest to the pointer, which is how a line chart gets its hover.

Monthly revenue with a forecast range
View of Monthly revenue with a forecast range

Line draws a path but does not register points, so on its own nothing can be hovered or reached with the arrow keys. Dots registers one point per dot, and NearestPointer axis="x" picks the column under the pointer. The dots need pixel positions, which is what the next section is about.

A value axis can run backwards. Where 1 is the best result, as with a search position or a league table, give y a descending domain: y={{ domain: [10, 1] }} on Chart, or domain={[10, 1]} on LineChart. Then 1 sits at the top, 10 at the bottom, and the line climbs as the result improves. Axis, Grid, Line, Area, Band, Target, the pointer and the arrow keys all follow the domain, and the arrow keys still step through the data in order. Explicit domains are never niced, so pick ends that suit the ticks.

Average search position by week
View of Average search position by week

Bars are the exception. A bar grows from the baseline, the domain value nearest zero, which on a reversed scale is the top edge: a bar for position 5 hangs from the top and is 4/9 of the plot tall, and a bar for position 1 has no length. That is consistent but rarely what a ranking wants, so use a line or dots for reversed scales.

Bridges and connectors #

Bars takes a from field: each bar then runs from from to its value instead of from zero, which makes floating steps. Connector draws the thin lines between neighbouring bars at the height where one step ends and the next begins.

Profit bridge from Q2 to Q3
View of Profit bridge from Q2 to Q3

tone takes a function per bar, so one Bars layer holds the totals, the gains and the losses. ariaLabel and segments report the change of each step instead of its end value, so the keyboard and screen readers walk the bridge left to right and hear "Costs, -30". Functions in props make this a client file.

Rows, custom marks and tables #

Swap the axes and a band scale on y gives rows. RowLabels writes a name and an optional second line in the margin, RowDividers rules between the rows, and a small component of your own marks the plan on each row with Dots (the grey dots).

Hours logged against plan, by team
View of Hours logged against plan, by team

DataTable is the visually hidden table that gives screen-reader users the same numbers. A chart renders one from its dataTable prop; use the component directly when you build the table yourself. See Getting started for why every chart needs a name, and LineChart for what the ready-made line chart arranges for you.

Two value axes #

Give Chart a y2 scale and a mark can draw on it with scale="y2". Line, Area, Band, Bars, ValueLabel, Target and Axis take scale; Grid always stays on y. y2 is linear only. Axis also takes tone, which tints its labels in a series' colour so a reader can tell which axis belongs to which series. Here views are hatched bars on the left scale, the busiest day is one solid bar with a pill, and unique visitors are a line on the right scale. A second one-row Line on the peak day draws the dot that stays on.

Page views and unique visitors per day
View of Page views and unique visitors per day

Bars registers the points, so hover and the arrow keys step through the days, and segments and ariaLabel carry both series into the tooltip and the announcement. The line has dots="none", so it draws no active ring and the tooltip says what its values are. Always pass dataTable.columns with both series: a chart with two scales is the one a screen-reader user most needs the numbers of.

Matching the ticks. The grid belongs to the left scale and nothing aligns the right axis to it, so the right axis's tick lines fall between the grid lines unless you line them up. Set both domains explicitly so that one is a clean multiple of the other ([0, 1200] and [0, 600]), and give both axes the same ticks count (here 6, which both domains round to: 0 to 1,200 in 200s, 0 to 600 in 100s). The tick labels are nice numbers, so a count you ask for can come back different; check the result, and adjust the domains until the two axes tick the same number of times.

Conventions #

The charts follow a few rules, so a prop that means one thing on one mark means the same on the next.

  • BarChart's x is the category and y the value, in both orientations.
  • at is scoped by its mark: a data index (a number) on ValueLabel, a category on ColumnHighlight and a value on a Connector link.
  • radius is the corner radius on Bars and ColumnHighlight, and the dot radius elsewhere.
  • Numbers in data follow one rule: numbers and numeric strings count, while blanks, booleans and other values are missing.
  • Toggles are bare booleans (legend, totals, grid, tooltip, …). Only showValues and showScale carry show, where the bare word would be ambiguous.
  • meta is a number on a WaterfallStep and an accessor on RankedBars. To carry more per step, extend the step type (WaterfallChart<MyStep>) rather than packing it into meta.

Defaults follow the reference cards, so they differ by chart:

  • Heights: Chart 240, LineChart 280, DotHistogram 220, WaffleColumns 200, BridgeChart 360.
  • Band padding: 0.2 on a band scale, 0.35 on BarChart, 0.45 on BridgeChart, 0.3 on WaffleColumns.
  • Tick counts: 5, and 6 on DotHistogram.
  • Tones: InlineBar, Meter, RangeMeter and DotCount default to accent (RangeMeter's reference to neutral). loss is chosen explicitly.

Ids of points and rows, as activeId, selectedId and onSelect see them:

  • RankedBars: the index in your data, unless you pass id.
  • WaterfallChart: 'start', then step.id ?? index, then 'end'. The end row's point.datum is a synthetic { label, value } created on every render, so compare by id === 'end', not by identity.
  • BridgeChart: 'start', then step.id ?? index.
  • StripPlot: "<series id>:<row id>".
  • LineChart: the x values as strings, so activeId takes '2025', not 2025. For the same reason 1 and '1' are the same x, and a repeated x is skipped with a warning. On a time scale they are ISO strings ('2026-01-04T00:00:00.000Z').
  • Heatmap: "<row>:<column>". Names containing : can collide (a:b + c and a + b:c), and each row and column name must be unique.

In a LineChart, give each series its own id. Hover snaps to the nearest x, and one tooltip lists every series there. A forecast that continues the actuals repeats the last actual value, so the two lines join, and the tooltip lists that value once. A series style is 'actual' (solid), 'forecast' (dashed, hollow dots) or 'scenario' (dashed, green).

Props #

Chart #

NameTypeDefaultRequiredDescription
activeIdId | null—No—
animateboolean—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

aspectRationumber—No

width / height. Used when height is not set.

chartIdstring—No

Prefix for pattern and mask ids. React's useId is only unique within one root, so set this when charts render in several React roots on one page.

childrenReactNode—No—
classNamestring—No—
datareadonly D[]—No—
dataTableDataTableSpec<D>—No

Visually hidden table of the data for screen readers. High-level charts set it by default.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
emptyReactNode"No data"No

Rendered instead of the plot when data is an empty array. Default "No data".

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

initialWidthnumber640No

Width used for server rendering and the first client render. Default 640.

keyboardHintstring"Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with `onSelect`No

Instructions read with the chart when it takes keyboard focus. Default: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." while the active point (or the first, before one is active) can be selected with onSelect. A custom text is used as is. Set it to translate the text; "" turns it off.

marginPartial<Margin>—No—
onActiveChange(id: Id | null, point: ChartPoint<D> | null) => void—No

Called with the new active id, and its point; point.datum is the row from data.

onSelect(id: Id, point: ChartPoint<D>) => void—No

Called on click, Enter or Space; point.datum is the row from data.

styleCSSProperties—No—
titlestring—No

Accessible name of the chart; also the default caption of the data table.

widthnumber—No

Fixed width in px; turns off container measuring.

xScaleSpec<D>—No—
yScaleSpec<D>—No—
y2LinearScaleSpec<D>—No

A second value scale, linear only, for marks with scale="y2". It shares the plot's height with y; the grid stays on y, and ticks of the two aren't aligned. <Axis side="right"> draws in the right margin, which is 0 by default, so set margin.right to fit its labels. Ignored, with a warning, when y is a band or point scale, or, from JavaScript, when it isn't linear.

Marks #

NameTypeDefaultRequiredDescription
alignBarAlign'center'No

Where a bar thinner than its band sits. Default 'center'.

ariaLabel(d: D, i: number) => string"<label>, <formatted value>"No

Screen-reader text per bar. Default ", ".

colorPerItem<D, string | undefined>—No

Any CSS color, including var(--x), replacing the tone's paint; tone stays as the semantic name. Applies only to bars with fill="solid": hatched bars paint from one pattern per tone, so they keep the tone and warn in development. Contrast in light and dark is up to you: var(--x) is the way to follow a theme. Forced-colors mode still uses system colors.

datareadonly D[]<Chart data>No

Defaults to .

fillPerItem<D, Fill>—No—
formatFormatSpec'number'No

Value format for tooltips and announcements. Default 'number'.

fromAccessor<D, number>the zero baselineNo

Start value per row; the bar runs from it to the value. Default: the zero baseline.

idAccessor<D, Id>—No—
interactivebooleantrueNo

Register points and hit areas for hover, keyboard and select. Set false on decorative layers. Default true.

labelAccessor<D, string>the category valueNo

Category label for tooltips and announcements. Defaults to the category value.

offsetnumber—No

Extra shift along the band axis in px, after align.

radiusnumberthe `--ch-radius` token (3px)No

Corner radius in px. Default: the --ch-radius token (3px).

scaleValueScale'y'No

The value scale to draw on, and whose field y defaults to. Default 'y'.

segments(d: D, i: number) => readonly TooltipSegment[]the label and the formatted valueNo

Tooltip pill segments per bar. Default: the label and the formatted value.

selectablePerItem<D, boolean>trueNo

False for bars the chart's onSelect skips (no pointer cursor either). Default true.

sizenumberthe band widthNo

Bar thickness in px. Default: the band width.

tonePerItem<D, Tone>—No—
trackbooleanfalseNo

Draw a faint track behind each bar across the whole value range. Default false.

xAccessor<D, string | number>the field on <Chart x>No

Defaults to the field on .

yAccessor<D, string | number>the field on <Chart y>No

Defaults to the field on .

NameTypeDefaultRequiredDescription
dashedbooleanfalseNo

Dashed stroke, e.g. for a forecast. Default false.

datareadonly D[]<Chart data>No

Defaults to .

dotsLineDots'filled'No

A dot at each value. Default 'filled'.

radiusnumber4No

Dot radius in px. Default 4.

scaleValueScale'y'No

The value scale to draw on, and whose field y defaults to. Default 'y'.

toneTone'accent'No

Default 'accent'.

xAccessor<D, string | number | Date>the field on <Chart x>No

Category or date field. Defaults to the field on .

yAccessor<D, number>the field on <Chart y>No

Value field. Defaults to the field on .

NameTypeDefaultRequiredDescription
betweenbooleanfalseNo

Fill only the gaps between bands, each from one band's far edge to the next band's near edge, so bars drawn over the area keep their own fill. Default false: one area through the centres.

datareadonly D[]<Chart data>No

Defaults to .

opacitynumber0.22No

Opacity at the top of the gradient; it fades to 0 at the baseline. Default 0.22.

scaleValueScale'y'No

The value scale to draw on, and whose field y defaults to. Default 'y'.

toneTone'accent'No

Default 'accent'.

xAccessor<D, string | number | Date>the field on <Chart x>No

Band or date field. Defaults to the field on .

yAccessor<D, number>the field on <Chart y>No

Value field. Defaults to the field on .

NameTypeDefaultRequiredDescription
dotsreadonly DotItem[]—Yes—
interactivebooleantrueNo

Register a point per dot. Set false when another layer registers the points. Default true.

radiusnumber—Yes—
NameTypeDefaultRequiredDescription
datareadonly D[]<Chart data>No

Defaults to .

highAccessor<D, number>—Yes—
lowAccessor<D, number>—Yes—
scaleValueScale'y'No

The value scale to draw on. Default 'y'.

toneTone'accent'No

Default 'accent'.

xAccessor<D, string | number | Date>the field on <Chart x>No

Category or date field. Defaults to the field on .

NameTypeDefaultRequiredDescription
fill'solid' | 'hatch''solid'No

'hatch' paints the tone's hatch pattern, e.g. for a locked span. Default 'solid'.

fromTimeInput—Yes

Where the region starts: a category on a point or band scale, e.g. the first forecast month, or a date (Date, epoch ms or ISO string) on a time scale.

toTimeInputthe last category, or the end of the time scaleNo

Where it ends. Default: the last category, or the end of the time scale.

toneTone'accent'No

Default 'accent'.

NameTypeDefaultRequiredDescription
labelstring—No

Text at the rule. On a vertical rule it sits to the right, or to the left when it wouldn't fit before the chart's right edge and does fit inside the plot on that side.

labelPosition'start' | 'end'—No—
positionnumber0.5, the centreNo

Where the rule sits within its category on a band or point scale, as a fraction of the step: 0 is the start edge, 1 the end edge. Default 0.5, the centre. Values outside 0 to 1 are clamped. Ignored, with a warning, on a linear or time scale.

scaleValueScale'y'No

The value scale y is on. Default 'y'. On 'y2', y is a number: that scale is linear. It has no effect on an x rule when the chart has a y2, and with no y2 it removes the rule, with a warning.

tickLengthnumber16No

Length of the tick variant in px. Default 16.

variant'line' | 'tick'—No—
xTimeInput—No

Draws a vertical rule at this x value: a number on a linear scale, or a date (Date, epoch ms or ISO string) on a time scale.

ynumber | string—No

Draws a horizontal rule at this y value, or at this category on a band or point scale.

NameTypeDefaultRequiredDescription
atstring | number—Yes

The band (category) to back.

padnumber12No

Extra room around the band, in px. Default 12.

radiusnumber16No

Corner radius in px. Default 16.

NameTypeDefaultRequiredDescription
fromInsetnumber0No

Pulls the start back from the far edge of from, in px. Default 0.

linksreadonly ConnectorLink[]—Yes—
toInsetnumber0No

Pushes the end into to, in px, e.g. to meet a bar that sits at the bottom of its band. Default 0.

NameTypeDefaultRequiredDescription
at'first' | 'last' | 'all' | 'max' | number—No

Which bars get a label. 'max' labels the highest finite bar, the first one on a tie.

datareadonly D[]<Chart data>No

Defaults to .

formatFormatSpec—No—
offsetnumber6No

Gap between the bar end and the label in px. Default 6.

scaleValueScale'y'No

The value scale to draw on, and whose field y defaults to. Default 'y'.

variant'text' | 'pill''text'No

'pill' draws the label on a filled rounded rectangle (part value-label-pill), sized from the text. The pill is 18 px tall and is clamped horizontally to the chart's width, not vertically: on the tallest bar it sits above the plot. A Chart with its default 20 px top margin needs a margin.top of at least 24 to fit it at the default offset. Default 'text'.

xAccessor<D, string | number>—No—
yAccessor<D, string | number>—No—

Axes and rows #

NameTypeDefaultRequiredDescription
extentreadonly [number, number]the scale's domainNo

Linear axes only: the value range to label when the scale runs past it, e.g. a waterfall that leaves room below its lowest total. Default: the scale's domain.

formatAxisFormat—No—
highlightstring | number—No

A tick value (e.g. a band) whose label is emphasized.

offsetnumber8No

Distance between the plot edge and the labels in px. Default 8.

scaleValueScale'y'No

The value scale to label on a left or right axis, independent of side. Default 'y'. Ignored, with a warning, on a top or bottom axis, which labels x.

sideAxisSide—Yes—
thinbooleantrueNo

Drop labels that would overlap. Default true.

ticksTickSpec'all'No

Default 'all'. A list of values works on a linear scale only; elsewhere it gives the default ticks and a development warning. Values outside the domain or extent are dropped, and thin can still drop labels that overlap.

toneTonethe muted axis colorNo

Tints the labels, to tie a value axis to its series. Default: the muted axis color.

NameTypeDefaultRequiredDescription
extentreadonly [number, number]the y domainNo

Value range to rule, like the axis extent. Default: the y domain.

ticksTickSpec'all' (about 5)No

Same as the y axis ticks, including a list of values, of which those outside the y domain or extent are dropped. Default 'all' (about 5).

NameTypeDefaultRequiredDescription
align'start' | 'end''start' on the left side and 'end' on the rightNo

Text alignment. Default 'start' on the left side and 'end' on the right.

datareadonly D[]<Chart data>No

Defaults to .

insetnumber0No

Moves the text inward, in px: from the chart's outer edge when the text aligns to it, and from the plot edge otherwise. Default 0.

maxWidthnumber—No

Longest text in px; longer text is cut with an ellipsis, and the full text goes in a <title>.

mutedbooleanfalseNo

Smaller, muted text for secondary columns such as "9 jobs". Default false.

position'middle' | 'above''middle'No

'middle' centres the text in its row; 'above' puts it at the top of the row. Default 'middle'.

side'left' | 'right''left'No

Which side of the plot the column sits on. Default 'left'.

subtextAccessor<D, string>—No

An optional second, muted line.

textAccessor<D, string>—Yes

The main line.

tonePerItem<D, Tone | undefined>inkNo

Text color role per row. Default: ink.

yAccessor<D, string | number>its fieldNo

Row field matching the band scale on . Defaults to its field.

NameTypeDefaultRequiredDescription
insetnumber0No

Distance in px from both outer edges. Default 0.

Interaction and overlays #

NameTypeDefaultRequiredDescription
content(point: ChartPoint) => ReactNode—No—
offsetnumber10No

Gap between the point and the tooltip in px. Default 10.

NameTypeDefaultRequiredDescription
axis'xy' | 'x''xy'No

'xy' measures straight-line distance; 'x' only the horizontal distance (columns). Default 'xy'.

radiusnumber24No

Largest distance in px that still activates a point. Default 24.

NameTypeDefaultRequiredDescription
clearance(left: number, right: number) => number—No

Given the pill's left and right edge in plot px, the y in plot px its bottom must stay above, e.g. the top of the labels it would otherwise cover. The pill rises past offset to clear it. A non-finite result sets no limit.

contentReactNode—No

Custom content instead of the pill.

hideWhileActivebooleantrueNo

Hide while any point is active, so the tooltip takes over. Default true.

idId—Yes

Id of the point to pin to: any point a mark registered.

offsetnumber10No

Gap between the point and the pill, in px. Default 10.

placement'auto' | 'top''auto'No

'auto' flips the pill below its point when there is no room above, like the tooltip. 'top' never flips: the pill stays above its point, clamped inside the chart's top edge. Default 'auto'.

segmentsreadonly TooltipSegment[]the point's own tooltip segmentsNo

Pill segments. Default: the point's own tooltip segments.

stembooleanfalseNo

A thin line from the pill to the point. Default false.

NameTypeDefaultRequiredDescription
captionstringthe chart titleNo

Defaults to the chart title.

columnsreadonly DataTableColumn<D>[]—Yes—
datareadonly D[]—Yes—