Charts
GroupedBarChart
Several series side by side inside each category. GroupedBarChart takes your rows, the field for the category and one entry per series, and handles the scales, the tooltip, the keyboard and the screen reader.
When to use it #
Use it to compare a few measures within each category: jobs per crew per quarter, revenue per service line per month. One row is one group, and each series is one bar in every group. Keep it to about four series, because the bars get thin. For one series, use BarChart. For plan against actual in rows, use ComparisonBars. For trends over many periods, LineChart usually reads better.
Import #
npm i tally-chartsimport { GroupedBarChart } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
Each series says which field it reads and how to name it. Props stay serializable here, so the chart renders in a server component. The third series sets tone: 'neutral' in its series object.
| Quarter | North | South | West |
|---|---|---|---|
| Q1 | 42 | 35 | 18 |
| Q2 | 48 | 38 | 27 |
| Q3 | 55 | 36 | 33 |
| Q4 | 61 | 44 | 41 |
import { GroupedBarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'grouped-bar-chart/jobs-by-crew',
title: 'Jobs completed by crew, per quarter',
rscSafe: true,
} satisfies ExampleMeta
const quarters = [
{ quarter: 'Q1', north: 42, south: 35, west: 18 },
{ quarter: 'Q2', north: 48, south: 38, west: 27 },
{ quarter: 'Q3', north: 55, south: 36, west: 33 },
{ quarter: 'Q4', north: 61, south: 44, west: 41 },
]
// Props stay serializable (no functions): the page is a server component.
export default function JobsByCrew() {
return (
<GroupedBarChart
data={quarters}
x="quarter"
series={[
{ id: 'north', label: 'North', value: 'north' },
{ id: 'south', label: 'South', value: 'south' },
{ id: 'west', label: 'West', value: 'west', tone: 'neutral' },
]}
domain={[0, 80]}
height={260}
title={meta.title}
description="North completed the most jobs every quarter, from 42 in Q1 to 61 in Q4."
/>
)
}
Series #
A BarSeries has an id that is unique within the chart, a label for the tooltip, the announcements and the data table header, a value accessor, and optionally a tone and a fill. Without a tone, series take the tones by position: accent, accent-soft, warn, neutral, gain, and then the order repeats. The default order never uses loss; choose it explicitly. Series are drawn in the order of the series array: left to right, or top to bottom when horizontal.
Tone is the series, and fill is the state. A row's fill applies to every bar of that row, so a forecast quarter reads as one thing. A series fill marks a whole series, such as last year. When both are set, the row's fill wins. The row fill is a function, so this example is a client component.
'use client'
import { GroupedBarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'grouped-bar-chart/forecast-quarter',
title: 'Jobs by crew, with a forecast quarter',
rscSafe: false,
} satisfies ExampleMeta
const quarters = [
{ quarter: 'Q1', north: 42, south: 35, west: 18, forecast: false },
{ quarter: 'Q2', north: 48, south: 38, west: 27, forecast: false },
{ quarter: 'Q3', north: 55, south: 36, west: 33, forecast: false },
{ quarter: 'Q4', north: 61, south: 44, west: 41, forecast: true },
]
// 'use client': `fill` is a function, which a server component cannot pass.
export default function ForecastQuarter() {
return (
<GroupedBarChart
data={quarters}
x="quarter"
series={[
{ id: 'north', label: 'North', value: 'north' },
{ id: 'south', label: 'South', value: 'south' },
{ id: 'west', label: 'West', value: 'west', tone: 'neutral' },
]}
fill={(d) => (d.forecast ? 'hatch' : undefined)}
domain={[0, 80]}
height={260}
title={meta.title}
description="Q4 is a forecast and is hatched. North is forecast to complete 61 jobs."
/>
)
}
orientation="horizontal" puts the categories on the left. x is still the category and the series values are still the values. Here last year is a 'hatch-fade' series. In both orientations grid and valueAxis are independent: valueAxis="none" hides the value axis and keeps the grid lines at the default ticks, and grid={false} removes the lines.
import { GroupedBarChart } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'grouped-bar-chart/horizontal',
title: 'Revenue by service line, this year and last',
rscSafe: true,
} satisfies ExampleMeta
const lines = [
{ line: 'Installation', current: 128, previous: 110 },
{ line: 'Maintenance', current: 94, previous: 99 },
{ line: 'Repairs', current: 71, previous: 64 },
{ line: 'Inspections', current: 39, previous: 41 },
]
export default function Horizontal() {
return (
<GroupedBarChart
data={lines}
x="line"
orientation="horizontal"
series={[
{ id: 'current', label: 'This year', value: 'current' },
{
id: 'previous',
label: 'Last year',
value: 'previous',
tone: 'neutral',
fill: 'hatch-fade',
},
]}
format="number"
title={meta.title}
description="Installation earned the most, 128 against 110 last year. Maintenance and inspections fell."
/>
)
}
Legend #
The chart has no legend of its own. Compose Legend with the same tones, as with LineChart. For a series without a tone, use the tone from the default order.
import { GroupedBarChart, Legend } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'grouped-bar-chart/with-legend',
title: 'Tickets closed by team, per month',
rscSafe: true,
} satisfies ExampleMeta
const months = [
{ month: 'Jul', billing: 64, platform: 48, support: 90 },
{ month: 'Aug', billing: 58, platform: 61, support: 84 },
{ month: 'Sep', billing: 71, platform: 55, support: 97 },
]
// The chart has no legend of its own: compose `Legend` with the same tones.
export default function WithLegend() {
return (
<div>
<Legend
items={[
{ label: 'Billing', tone: 'accent' },
{ label: 'Platform', tone: 'accent-soft' },
{ label: 'Support', tone: 'warn' },
]}
/>
<GroupedBarChart
data={months}
x="month"
series={[
{ id: 'billing', label: 'Billing', value: 'billing' },
{ id: 'platform', label: 'Platform', value: 'platform' },
{ id: 'support', label: 'Support', value: 'support' },
]}
domain={[0, 120]}
height={260}
title={meta.title}
description="Support closed the most tickets every month. Platform closed the fewest in July and September."
/>
</div>
)
}
Value labels #
valueLabel="all" (the default) writes the value above each bar, or beside it when horizontal. A horizontal chart always draws its value labels. In a vertical chart, when any label is wider than its bar, no label is drawn at that width, and the values stay in the tooltip and the data table. A downward bar whose label does not fit below it gets the label above its base. Use valueLabel="none" to turn the labels off.
Props #
| 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 |
axis | TickSpec | 'none' | every category | No | Category axis ticks, or 'none'. Default: every category. |
axisFormat | AxisFormat | the category itself | No | Category axis labels: a function of the category. Number presets and date formats don't apply to categories and are ignored with a development warning. Default: the category itself. |
chartId | string | — | No | Prefix for pattern and mask ids. React's |
children | ReactNode | — | No | — |
className | string | — | No | — |
data | readonly D[] | — | Yes | — |
dataTable | boolean | DataTableOptions | true | No | Hidden data table for screen readers: |
description | string | — | No | Accessible description, usually the takeaway sentence. |
dimInactive | boolean | — | No | — |
domain | readonly [number, number] | every series and the target, including zero, rounded to nice ticks | No | Value domain. Default: every series and the target, including zero, rounded to nice ticks. |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
fill | PerItem<D, Fill | undefined> | undefined | No | Fill for every bar of a row, e.g. 'hatch' for a forecast period. |
format | FormatSpec | 'number' | No | Format for tooltips, announcements and the data table. Default 'number'. |
gap | number | 4 | No | Gap between the bars of a group in px. Default 4. |
grid | boolean | true | No | Grid lines at the value ticks. Default true. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | the data index | No | Row id. A bar's id is |
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 |
label | Accessor<D, string> | `x` | No | Category label for tooltips, announcements and the data table. Defaults to |
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; |
orientation | 'vertical' | 'horizontal' | 'vertical' | No | Default 'vertical'. |
padding | number | 0.3 | No | Padding between groups, 0–1 of the step. Default 0.3. |
series | readonly BarSeries<D>[] | — | Yes | One bar per series in every group, in this order. |
style | CSSProperties | — | No | — |
target | number | { value: number; label?: string } | — | No | A target value, optionally with a label. |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tooltip | ChartTooltip<D> | true | No | Tooltip on hover and focus: |
valueAxis | TickSpec | 'none' | nice ticks | No | Value axis ticks, or 'none'. Default: nice ticks. |
valueAxisFormat | AxisFormat | `format` | No | Value axis labels. Default: |
valueFormat | FormatSpec | `format` | No | Format for value labels. Defaults to |
valueLabel | 'all' | 'none' | 'all' | No | 'all' labels every bar when the labels fit. Default 'all'. |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | Accessor<D, string | number> | — | Yes | Category field: the band axis in both orientations. One row is one group. |
Series and points #
A bar's id is ${rowId}:${series.id}, where the row id is the id accessor or the data index. Every bar is a point. In onSelect and onActiveChange, the ChartPoint has seriesId with the id of the series, series with its label, and datum with your row. You do not need to parse the id.
Keyboard and screen readers #
The chart is a single tab stop. Arrow keys walk the bars in visual order, group by group and series by series. Home and End jump to the first and last bar, Enter or Space selects the active bar when the chart has onSelect, and Esc clears the active bar.
Screen readers get the title and description, then an announcement for each bar the keyboard moves to, such as “North, 3 of 4, Q3, 55”: the series, the position within the series, then the category and the formatted value. A visually hidden data table follows the chart, with one row per category and one column per series.
In forced colors mode (Windows high contrast), tones collapse to a few system colors and several share one: accent becomes Highlight, accent-soft and neutral GrayText, warn and gain CanvasText. Series that share a color are told apart by their position in each group, the gap between the bars keeps them separate, and the data table carries the values.
The full model is in the accessibility guide.