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.
import {
Axis,
Bars,
Callout,
Chart,
ColumnHighlight,
Grid,
Target,
Tooltip,
ValueLabel,
} from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/bars-and-axes',
title: 'Gross margin by week, against a 40% target',
rscSafe: true,
} satisfies ExampleMeta
const percent = { preset: 'percent', digits: 0 } as const
const weeks = [
{ week: 'W1', margin: 34 },
{ week: 'W2', margin: 35 },
{ week: 'W3', margin: 31 },
{ week: 'W4', margin: 42 },
{ week: 'W5', margin: 45 },
{ week: 'W6', margin: 39 },
]
// Chart owns the scales, the size and the interaction; every child reads them from context.
// Props stay serializable (strings and numbers, no functions): the page is a server component.
export default function BarsAndAxes() {
return (
<Chart
data={weeks}
x={{ type: 'band', field: 'week', padding: 0.35 }}
y={{ field: 'margin', domain: [0, 50] }}
margin={{ top: 64, left: 36 }}
height={280}
title={meta.title}
description="Margin passed the 40% target in W4 and peaked at 45% in W5."
>
<Grid ticks={5} />
<ColumnHighlight at="W5" />
<Target y={40} label="Target 40%" labelPosition="start" />
<Bars id="week" format={percent} fill="hatch-fade" />
<ValueLabel at="all" format={percent} />
<Callout
id="W5"
offset={30}
segments={[{ value: 'Best week' }, { value: '45%', tone: 'gain' }]}
/>
<Axis side="left" ticks={5} />
<Axis side="bottom" highlight="W5" />
<Tooltip />
</Chart>
)
}
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.
import { Axis, Bars, Chart, Grid, Target, Tooltip } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/threshold-between-buckets',
title: 'Scores by bucket, with a pass mark at 73',
rscSafe: true,
} satisfies ExampleMeta
const scores = [
{ range: '0–9', students: 1 },
{ range: '10–19', students: 2 },
{ range: '20–29', students: 4 },
{ range: '30–39', students: 7 },
{ range: '40–49', students: 11 },
{ range: '50–59', students: 16 },
{ range: '60–69', students: 19 },
{ range: '70–79', students: 14 },
{ range: '80–89', students: 8 },
{ range: '90–99', students: 3 },
]
// A bucket is 10 wide, so 73 sits 0.3 of the way across "70–79": position = (73 - 70) / 10.
export default function ThresholdBetweenBuckets() {
return (
<Chart
data={scores}
x={{ type: 'band', field: 'range', padding: 0.2 }}
y={{ field: 'students' }}
margin={{ left: 36 }}
height={240}
title={meta.title}
description="Most students scored between 50 and 79. The pass mark of 73 falls inside the 70 to 79 bucket."
>
<Grid ticks={4} />
<Bars id="range" />
<Target x="70–79" position={0.3} label="Pass mark 73" />
<Axis side="left" ticks={4} />
<Axis side="bottom" />
<Tooltip />
</Chart>
)
}
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.
'use client'
import {
Area,
Axis,
Band,
Chart,
Dots,
Grid,
Line,
NearestPointer,
Region,
Tooltip,
useChart,
} from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/line-area-band',
title: 'Monthly revenue with a forecast range',
rscSafe: false,
} satisfies ExampleMeta
const months = [
{ month: 'Jan', revenue: 410, low: 410, high: 410 },
{ month: 'Feb', revenue: 455, low: 455, high: 455 },
{ month: 'Mar', revenue: 498, low: 498, high: 498 },
{ month: 'Apr', revenue: 530, low: 530, high: 530 },
{ month: 'May', revenue: 590, low: 590, high: 590 },
{ month: 'Jun', revenue: 640, low: 640, high: 640 },
{ month: 'Jul', revenue: 700, low: 660, high: 740 },
{ month: 'Aug', revenue: 745, low: 690, high: 800 },
{ month: 'Sep', revenue: 790, low: 720, high: 860 },
{ month: 'Oct', revenue: 850, low: 760, high: 940 },
]
// Line draws a path but registers no points, so nothing can be hovered or reached with the
// arrow keys. Dots takes pixel positions, which only exist inside the chart, so this component
// reads the scales with useChart(). A hook cannot run in a Server Component, hence 'use client'
// at the top of the file (the reference compositions do the same).
function RevenueDots({ rows }: { rows: typeof months }) {
const { x, y } = useChart()
if (x.kind !== 'point' || y.kind !== 'linear') return null
return (
<Dots
radius={4}
dots={rows.flatMap((row, index) => {
const cx = x.scale(row.month)
if (cx === undefined) return []
return [
{
key: row.month,
id: row.month,
datum: row,
cx,
cy: y.scale(row.revenue),
tone: 'accent' as const,
soft: index >= 6,
label: `${row.month}, ${row.revenue}k`,
segments: [{ value: row.month }, { value: `${row.revenue}k` }],
},
]
})}
/>
)
}
export default function LineAreaBand() {
return (
<Chart
data={months}
x={{ type: 'point', field: 'month' }}
y={{ field: 'revenue', domain: [300, 1000] }}
margin={{ left: 44 }}
height={280}
title={meta.title}
description="Revenue grew from 410k to 640k over six months; the forecast range reaches 760k to 940k in October."
>
<Region from="Jul" />
<Grid ticks={5} />
<Band data={months.slice(5)} low="low" high="high" tone="accent-soft" />
<Area y="revenue" opacity={0.18} />
<Line y="revenue" dots="none" />
<RevenueDots rows={months} />
<Axis side="left" ticks={5} />
<Axis side="bottom" />
<NearestPointer axis="x" radius={32} />
<Tooltip />
</Chart>
)
}
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.
import { LineChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/reversed-position',
title: 'Average search position by week',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'W1', position: 9.4 },
{ week: 'W2', position: 8.8 },
{ week: 'W3', position: 8.1 },
{ week: 'W4', position: 7.2 },
{ week: 'W5', position: 6.9 },
{ week: 'W6', position: 5.6 },
{ week: 'W7', position: 5.9 },
{ week: 'W8', position: 4.3 },
{ week: 'W9', position: 3.8 },
{ week: 'W10', position: 3.1 },
]
// Position 1 is the best result, so the domain runs from 10 down to 1: the line climbs as the
// page ranks higher. A reversed domain works the same on Chart's `y`.
export default function ReversedPosition() {
return (
<LineChart
data={weeks}
x="week"
series={[{ id: 'position', label: 'Average position', value: 'position' }]}
domain={[10, 1]}
target={{ value: 3, label: 'Goal: top 3' }}
format={{ preset: 'number', digits: 1 }}
yAxis={5}
height={240}
title={meta.title}
description="The page climbed from an average position of 9.4 in W1 to 3.1 in W10."
/>
)
}
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.
'use client'
import { Axis, Bars, Chart, Connector, ValueLabel } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/bridge-connector',
title: 'Profit bridge from Q2 to Q3',
rscSafe: false,
} satisfies ExampleMeta
// Each step floats between `base` and `top`: Bars reads the end from `y` and the start from `from`.
const steps = [
{ step: 'Q2', base: 0, top: 120, kind: 'total' },
{ step: 'Volume', base: 120, top: 150, kind: 'gain' },
{ step: 'Price', base: 150, top: 170, kind: 'gain' },
{ step: 'Costs', base: 140, top: 170, kind: 'loss' },
{ step: 'Returns', base: 128, top: 140, kind: 'loss' },
{ step: 'Q3', base: 0, top: 128, kind: 'total' },
]
type Step = (typeof steps)[number]
// `tone` takes a function per bar, so one layer holds the whole bridge. One layer also keeps the
// bars registered in x order, which is the order the keyboard and screen readers walk them in.
const toneOf = (s: Step) => (s.kind === 'gain' ? 'gain' : s.kind === 'loss' ? 'loss' : 'accent')
// A floating bar's value is its end (`top`), so say the change in the announcement and tooltip.
const change = (s: Step) =>
s.kind === 'total' ? `${s.top}` : s.kind === 'gain' ? `+${s.top - s.base}` : `-${s.top - s.base}`
// The functions in `tone`, `ariaLabel` and `segments` cannot cross the server boundary, so this
// file starts with 'use client'.
export default function BridgeConnector() {
return (
<Chart
data={steps}
x={{ type: 'band', field: 'step', padding: 0.4 }}
y={{ field: 'top', domain: [0, 200] }}
margin={{ top: 28 }}
height={280}
title={meta.title}
description="Profit rose from 120 to 170 on volume and price, then fell back to 128 after costs and returns."
>
<Connector
links={[
{ at: 120, from: 'Q2', to: 'Volume' },
{ at: 150, from: 'Volume', to: 'Price' },
{ at: 170, from: 'Price', to: 'Costs' },
{ at: 140, from: 'Costs', to: 'Returns' },
{ at: 128, from: 'Returns', to: 'Q3' },
]}
/>
<Bars
x="step"
y="top"
from="base"
id="step"
tone={toneOf}
ariaLabel={(s) => `${s.step}, ${change(s)}`}
segments={(s) => [{ value: s.step }, { value: change(s) }]}
/>
<ValueLabel at="first" />
<ValueLabel at="last" />
<Axis side="bottom" />
</Chart>
)
}
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).
'use client'
import {
Bars,
Chart,
DataTable,
Dots,
RowDividers,
RowLabels,
Tooltip,
TooltipPill,
useChart,
} from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/rows-and-custom-marks',
title: 'Hours logged against plan, by team',
rscSafe: false,
} satisfies ExampleMeta
interface TeamRow {
team: string
lead: string
actual: number
plan: number
}
const teams: TeamRow[] = [
{ team: 'Platform', lead: 'Ines', actual: 412, plan: 380 },
{ team: 'Payments', lead: 'Marek', actual: 355, plan: 360 },
{ team: 'Growth', lead: 'Aiko', actual: 298, plan: 340 },
{ team: 'Data', lead: 'Tomás', actual: 276, plan: 250 },
{ team: 'Support', lead: 'Priya', actual: 190, plan: 220 },
]
// The plan marker sits at a pixel position that depends on the chart's scales, which only exist
// inside <Chart>. Reading them takes the useChart() hook, and a hook cannot run in a Server
// Component, so this file starts with 'use client' (the reference compositions do the same).
function PlanMarkers({ rows }: { rows: readonly TeamRow[] }) {
const { x, y } = useChart()
if (x.kind !== 'linear' || y.kind !== 'band') return null
return (
<Dots
radius={4}
interactive={false}
dots={rows.flatMap((row) => {
const top = y.scale(row.team)
if (top === undefined) return []
return [
{
key: row.team,
id: row.team,
datum: row,
cx: x.scale(row.plan),
cy: top + y.scale.bandwidth() / 2,
tone: 'neutral' as const,
label: `${row.team} plan, ${row.plan} hours`,
},
]
})}
/>
)
}
export default function RowsAndCustomMarks() {
return (
<>
<Chart
data={teams}
x={{ field: 'actual', domain: [0, 450] }}
y={{ type: 'band', field: 'team', padding: 0.4 }}
margin={{ top: 8, right: 16, bottom: 8, left: 120 }}
height={232}
title={meta.title}
description="Platform and Data ran over plan; Growth and Support came in under it."
>
<RowDividers inset={8} />
<RowLabels text="team" subtext="lead" inset={8} />
<Bars id="team" format={{ preset: 'number', digits: 0 }} />
<PlanMarkers rows={teams} />
<Tooltip
content={(point) => {
const row = point.datum as TeamRow
return (
<TooltipPill
segments={[
{ value: row.team },
{ value: `${row.actual} h` },
{ value: `plan ${row.plan} h` },
]}
/>
)
}}
/>
</Chart>
{/* Chart's own `dataTable` prop does the same job; DataTable is the piece it renders. */}
<DataTable
data={teams}
caption="Hours logged against plan, by team"
columns={[
{ header: 'Team', value: (d) => d.team },
{ header: 'Logged', value: (d) => String(d.actual) },
{ header: 'Planned', value: (d) => String(d.plan) },
]}
/>
</>
)
}
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.
'use client'
import { Axis, Bars, Chart, Grid, Legend, Line, Tooltip, ValueLabel } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'composition/dual-axis-traffic',
title: 'Page views and unique visitors per day',
rscSafe: false,
} satisfies ExampleMeta
type Day = { day: string; views: number; uniques: number; peak: boolean }
const days: Day[] = [
[540, 260],
[610, 300],
[480, 240],
[720, 350],
[850, 410],
[790, 380],
[1040, 470],
[660, 330],
[590, 290],
[700, 340],
[880, 420],
[830, 400],
[760, 370],
[920, 440],
].map(([views = 0, uniques = 0], i) => ({
day: `Oct ${18 + i}`,
views,
uniques,
peak: views === 1040,
}))
const peak = days.filter((d) => d.peak)
// Both domains are explicit and both axes ask for 6 ticks, so the 7 tick lines sit at the same
// heights: 0, 200 ... 1200 views against 0, 100 ... 600 visitors.
// Functions as props (fill, color, segments, the data table), so the file is a client component.
export default function DualAxisTraffic() {
return (
<div style={{ display: 'grid', gap: 12 }}>
<Legend
items={[
{ label: 'Views', fill: 'hatch' },
{ label: 'Peak day', color: 'var(--ch-warn)' },
{ label: 'Unique visitors', shape: 'line', tone: 'accent' },
]}
/>
<Chart<Day>
data={days}
x={{ type: 'band', field: 'day', padding: 0.3 }}
y={{ field: 'views', domain: [0, 1200] }}
y2={{ field: 'uniques', domain: [0, 600] }}
margin={{ top: 32, left: 44, right: 44 }}
height={280}
title={meta.title}
description="Views peaked at 1,040 on Oct 24; unique visitors followed the same shape on their own scale."
dataTable={{
columns: [
{ header: 'Day', value: (d) => d.day },
{ header: 'Views', value: (d) => String(d.views) },
{ header: 'Unique visitors', value: (d) => String(d.uniques) },
],
}}
>
<Grid ticks={6} />
<Bars<Day>
id="day"
tone="neutral"
fill={(d) => (d.peak ? 'solid' : 'hatch')}
color={(d) => (d.peak ? 'var(--ch-warn)' : undefined)}
segments={(d) => [
{ value: d.day },
{ value: `${d.views.toLocaleString('en-US')} views` },
{ value: `${d.uniques.toLocaleString('en-US')} unique`, tone: 'accent' },
]}
ariaLabel={(d) => `${d.day}, ${d.views} views, ${d.uniques} unique visitors`}
/>
<ValueLabel at="max" variant="pill" />
<Line scale="y2" dots="none" />
<Line data={peak} scale="y2" />
<Axis side="left" ticks={6} />
<Axis side="right" scale="y2" tone="accent" ticks={6} />
<Axis side="bottom" />
<Tooltip />
</Chart>
</div>
)
}
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'sxis the category andythe value, in both orientations.atis scoped by its mark: a data index (a number) onValueLabel, a category onColumnHighlightand a value on aConnectorlink.radiusis the corner radius onBarsandColumnHighlight, 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, …). OnlyshowValuesandshowScalecarryshow, where the bare word would be ambiguous. metais a number on aWaterfallStepand an accessor onRankedBars. To carry more per step, extend the step type (WaterfallChart<MyStep>) rather than packing it intometa.
Defaults follow the reference cards, so they differ by chart:
- Heights:
Chart240,LineChart280,DotHistogram220,WaffleColumns200,BridgeChart360. - Band padding: 0.2 on a band scale, 0.35 on
BarChart, 0.45 onBridgeChart, 0.3 onWaffleColumns. - Tick counts: 5, and 6 on
DotHistogram. - Tones:
InlineBar,Meter,RangeMeterandDotCountdefault toaccent(RangeMeter's reference toneutral).lossis chosen explicitly.
Ids of points and rows, as activeId, selectedId and onSelect see them:
RankedBars: the index in your data, unless you passid.WaterfallChart:'start', thenstep.id ?? index, then'end'. The end row'spoint.datumis a synthetic{ label, value }created on every render, so compare byid === 'end', not by identity.BridgeChart:'start', thenstep.id ?? index.StripPlot:"<series id>:<row id>".LineChart: the x values as strings, soactiveIdtakes'2025', not2025. For the same reason1and'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+canda+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 #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | Id | null | — | No | — |
animate | boolean | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
aspectRatio | number | — | No | width / height. Used when |
chartId | string | — | No | Prefix for pattern and mask ids. React's |
children | ReactNode | — | No | — |
className | string | — | No | — |
data | readonly D[] | — | No | — |
dataTable | DataTableSpec<D> | — | No | Visually hidden table of the data for screen readers. High-level charts set it by default. |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
initialWidth | number | 640 | No | Width used for server rendering and the first client render. Default 640. |
keyboardHint | string | "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 |
margin | Partial<Margin> | — | No | — |
onActiveChange | (id: Id | null, point: ChartPoint<D> | null) => void | — | No | Called with the new active id, and its point; |
onSelect | (id: Id, point: ChartPoint<D>) => void | — | No | Called on click, Enter or Space; |
style | CSSProperties | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | ScaleSpec<D> | — | No | — |
y | ScaleSpec<D> | — | No | — |
y2 | LinearScaleSpec<D> | — | No | A second value scale, linear only, for marks with |
Marks #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
align | BarAlign | '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 ", ". |
color | PerItem<D, string | undefined> | — | No | Any CSS color, including |
data | readonly D[] | <Chart data> | No | Defaults to . |
fill | PerItem<D, Fill> | — | No | — |
format | FormatSpec | 'number' | No | Value format for tooltips and announcements. Default 'number'. |
from | Accessor<D, number> | the zero baseline | No | Start value per row; the bar runs from it to the value. Default: the zero baseline. |
id | Accessor<D, Id> | — | No | — |
interactive | boolean | true | No | Register points and hit areas for hover, keyboard and select. Set false on decorative layers. Default true. |
label | Accessor<D, string> | the category value | No | Category label for tooltips and announcements. Defaults to the category value. |
offset | number | — | No | Extra shift along the band axis in px, after |
radius | number | the `--ch-radius` token (3px) | No | Corner radius in px. Default: the |
scale | ValueScale | 'y' | No | The value scale to draw on, and whose field |
segments | (d: D, i: number) => readonly TooltipSegment[] | the label and the formatted value | No | Tooltip pill segments per bar. Default: the label and the formatted value. |
selectable | PerItem<D, boolean> | true | No | False for bars the chart's |
size | number | the band width | No | Bar thickness in px. Default: the band width. |
tone | PerItem<D, Tone> | — | No | — |
track | boolean | false | No | Draw a faint track behind each bar across the whole value range. Default false. |
x | Accessor<D, string | number> | the field on <Chart x> | No | Defaults to the field on . |
y | Accessor<D, string | number> | the field on <Chart y> | No | Defaults to the field on . |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
dashed | boolean | false | No | Dashed stroke, e.g. for a forecast. Default false. |
data | readonly D[] | <Chart data> | No | Defaults to . |
dots | LineDots | 'filled' | No | A dot at each value. Default 'filled'. |
radius | number | 4 | No | Dot radius in px. Default 4. |
scale | ValueScale | 'y' | No | The value scale to draw on, and whose field |
tone | Tone | 'accent' | No | Default 'accent'. |
x | Accessor<D, string | number | Date> | the field on <Chart x> | No | Category or date field. Defaults to the field on . |
y | Accessor<D, number> | the field on <Chart y> | No | Value field. Defaults to the field on . |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
between | boolean | false | No | 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. |
data | readonly D[] | <Chart data> | No | Defaults to . |
opacity | number | 0.22 | No | Opacity at the top of the gradient; it fades to 0 at the baseline. Default 0.22. |
scale | ValueScale | 'y' | No | The value scale to draw on, and whose field |
tone | Tone | 'accent' | No | Default 'accent'. |
x | Accessor<D, string | number | Date> | the field on <Chart x> | No | Band or date field. Defaults to the field on . |
y | Accessor<D, number> | the field on <Chart y> | No | Value field. Defaults to the field on . |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
dots | readonly DotItem[] | — | Yes | — |
interactive | boolean | true | No | Register a point per dot. Set false when another layer registers the points. Default true. |
radius | number | — | Yes | — |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
data | readonly D[] | <Chart data> | No | Defaults to . |
high | Accessor<D, number> | — | Yes | — |
low | Accessor<D, number> | — | Yes | — |
scale | ValueScale | 'y' | No | The value scale to draw on. Default 'y'. |
tone | Tone | 'accent' | No | Default 'accent'. |
x | Accessor<D, string | number | Date> | the field on <Chart x> | No | Category or date field. Defaults to the field on . |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
fill | 'solid' | 'hatch' | 'solid' | No | 'hatch' paints the tone's hatch pattern, e.g. for a locked span. Default 'solid'. |
from | TimeInput | — | Yes | Where the region starts: a category on a point or band scale, e.g. the first forecast month, or a date ( |
to | TimeInput | the last category, or the end of the time scale | No | Where it ends. Default: the last category, or the end of the time scale. |
tone | Tone | 'accent' | No | Default 'accent'. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
label | string | — | 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 | — |
position | number | 0.5, the centre | No | 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. |
scale | ValueScale | 'y' | No | The value scale |
tickLength | number | 16 | No | Length of the tick variant in px. Default 16. |
variant | 'line' | 'tick' | — | No | — |
x | TimeInput | — | No | Draws a vertical rule at this x value: a number on a linear scale, or a date ( |
y | number | string | — | No | Draws a horizontal rule at this y value, or at this category on a band or point scale. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
at | string | number | — | Yes | The band (category) to back. |
pad | number | 12 | No | Extra room around the band, in px. Default 12. |
radius | number | 16 | No | Corner radius in px. Default 16. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
fromInset | number | 0 | No | Pulls the start back from the far edge of |
links | readonly ConnectorLink[] | — | Yes | — |
toInset | number | 0 | No | Pushes the end into |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
at | 'first' | 'last' | 'all' | 'max' | number | — | No | Which bars get a label. 'max' labels the highest finite bar, the first one on a tie. |
data | readonly D[] | <Chart data> | No | Defaults to . |
format | FormatSpec | — | No | — |
offset | number | 6 | No | Gap between the bar end and the label in px. Default 6. |
scale | ValueScale | 'y' | No | The value scale to draw on, and whose field |
variant | 'text' | 'pill' | 'text' | No | 'pill' draws the label on a filled rounded rectangle (part |
x | Accessor<D, string | number> | — | No | — |
y | Accessor<D, string | number> | — | No | — |
Axes and rows #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
extent | readonly [number, number] | the scale's domain | No | 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. |
format | AxisFormat | — | No | — |
highlight | string | number | — | No | A tick value (e.g. a band) whose label is emphasized. |
offset | number | 8 | No | Distance between the plot edge and the labels in px. Default 8. |
scale | ValueScale | 'y' | No | The value scale to label on a left or right axis, independent of |
side | AxisSide | — | Yes | — |
thin | boolean | true | No | Drop labels that would overlap. Default true. |
ticks | TickSpec | '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 |
tone | Tone | the muted axis color | No | Tints the labels, to tie a value axis to its series. Default: the muted axis color. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
extent | readonly [number, number] | the y domain | No | Value range to rule, like the axis |
ticks | TickSpec | 'all' (about 5) | No | Same as the y axis |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
align | 'start' | 'end' | 'start' on the left side and 'end' on the right | No | Text alignment. Default 'start' on the left side and 'end' on the right. |
data | readonly D[] | <Chart data> | No | Defaults to . |
inset | number | 0 | No | 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. |
maxWidth | number | — | No | Longest text in px; longer text is cut with an ellipsis, and the full text goes in a |
muted | boolean | false | No | 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'. |
subtext | Accessor<D, string> | — | No | An optional second, muted line. |
text | Accessor<D, string> | — | Yes | The main line. |
tone | PerItem<D, Tone | undefined> | ink | No | Text color role per row. Default: ink. |
y | Accessor<D, string | number> | its field | No | Row field matching the band scale on . Defaults to its field. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
inset | number | 0 | No | Distance in px from both outer edges. Default 0. |
Interaction and overlays #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
content | (point: ChartPoint) => ReactNode | — | No | — |
offset | number | 10 | No | Gap between the point and the tooltip in px. Default 10. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
axis | 'xy' | 'x' | 'xy' | No | 'xy' measures straight-line distance; 'x' only the horizontal distance (columns). Default 'xy'. |
radius | number | 24 | No | Largest distance in px that still activates a point. Default 24. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
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 |
content | ReactNode | — | No | Custom content instead of the pill. |
hideWhileActive | boolean | true | No | Hide while any point is active, so the tooltip takes over. Default true. |
id | Id | — | Yes | Id of the point to pin to: any point a mark registered. |
offset | number | 10 | No | Gap between the point and the pill, in px. Default 10. |
placement | 'auto' | 'top' | 'auto' | No |
|
segments | readonly TooltipSegment[] | the point's own tooltip segments | No | Pill segments. Default: the point's own tooltip segments. |
stem | boolean | false | No | A thin line from the pill to the point. Default false. |
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
caption | string | the chart title | No | Defaults to the chart title. |
columns | readonly DataTableColumn<D>[] | — | Yes | — |
data | readonly D[] | — | Yes | — |