On this page

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 #

Terminal
npm i tally-charts
app/jobs.tsx
import { 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.

Jobs completed by crew, per quarter
View of Jobs completed by crew, per quarter
Jobs completed by crew, per quarter
QuarterNorthSouthWest
Q1423518
Q2483827
Q3553633
Q4614441

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.

Jobs by crew, with a forecast quarter
View of Jobs by crew, with a forecast quarter

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.

Revenue by service line, this year and last
View of Revenue by service line, this year and last

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.

Tickets closed by team, per month
View of Tickets closed by team, per month

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 #

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.

axisTickSpec | 'none'every categoryNo

Category axis ticks, or 'none'. Default: every category.

axisFormatAxisFormatthe category itselfNo

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.

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[]—Yes—
dataTableboolean | DataTableOptionstrueNo

Hidden data table for screen readers: true, false, or { caption, columns } to set its caption and rename column headers. Default true.

descriptionstring—No

Accessible description, usually the takeaway sentence.

dimInactiveboolean—No—
domainreadonly [number, number]every series and the target, including zero, rounded to nice ticksNo

Value domain. Default: every series and the target, including zero, rounded to nice ticks.

emptyReactNode"No data"No

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

fillPerItem<D, Fill | undefined>undefinedNo

Fill for every bar of a row, e.g. 'hatch' for a forecast period. undefined keeps each series' own fill. Default: undefined.

formatFormatSpec'number'No

Format for tooltips, announcements and the data table. Default 'number'.

gapnumber4No

Gap between the bars of a group in px. Default 4.

gridbooleantrueNo

Grid lines at the value ticks. Default true.

heightnumber240 unless `aspectRatio` is setNo

Height in px. Default 240 unless aspectRatio is set.

idAccessor<D, Id>the data indexNo

Row id. A bar's id is ${rowId}:${series.id}. Default: the data index.

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.

labelAccessor<D, string>`x`No

Category label for tooltips, announcements and the data table. Defaults to x.

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.

orientation'vertical' | 'horizontal''vertical'No

Default 'vertical'.

paddingnumber0.3No

Padding between groups, 0–1 of the step. Default 0.3.

seriesreadonly BarSeries<D>[]—Yes

One bar per series in every group, in this order.

styleCSSProperties—No—
targetnumber | { value: number; label?: string }—No

A target value, optionally with a label.

titlestring—No

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

tooltipChartTooltip<D>trueNo

Tooltip on hover and focus: true for the default pill, or a function that renders the content for a point (point.datum is your row). Default true.

valueAxisTickSpec | 'none'nice ticksNo

Value axis ticks, or 'none'. Default: nice ticks.

valueAxisFormatAxisFormat`format`No

Value axis labels. Default: format.

valueFormatFormatSpec`format`No

Format for value labels. Defaults to format.

valueLabel'all' | 'none''all'No

'all' labels every bar when the labels fit. Default 'all'.

widthnumber—No

Fixed width in px; turns off container measuring.

xAccessor<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.