Charts
WaffleColumns
A total for each period, counted in dots. Every period is a column, and each dot in it stands for the same unit, so the height of a column is how many units the period holds.
When to use it #
Use WaffleColumns for a sum per period where the size of each period should read as a count of things: signups per week, claims per month, dollars lost per week. unit sets the value of a dot and wide the dots across a column. The largest column is solid and the others soft (peak={false} makes them all solid), and a pill above it names the peak (callout). group labels runs of periods under their columns, such as the month, and groupTone picks a tone for each group.
If you want to see the individual items rather than a total, use DotHistogram: one dot per item, stacked by value. To compare several measures of the same items, use StripPlot: one row of dots per measure.
Import #
npm i tally-chartsimport { WaffleColumns } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
Weeks in two months. group names the month under its columns and the default callout pins “Peak” above the biggest week. Every prop is serializable.
| Week | Signups | Month |
|---|---|---|
| Jul 6 | 410 | July |
| Jul 13 | 460 | July |
| Jul 20 | 380 | July |
| Jul 27 | 520 | July |
| Aug 3 | 490 | August |
| Aug 10 | 1,180 | August |
| Aug 17 | 560 | August |
| Aug 24 | 540 | August |
| Aug 31 | 610 | August |
import { WaffleColumns } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'waffle-columns/weekly-signups',
title: 'Newsletter signups per week',
rscSafe: true,
} satisfies ExampleMeta
const weeks = [
{ week: 'Jul 6', signups: 410, month: 'July' },
{ week: 'Jul 13', signups: 460, month: 'July' },
{ week: 'Jul 20', signups: 380, month: 'July' },
{ week: 'Jul 27', signups: 520, month: 'July' },
{ week: 'Aug 3', signups: 490, month: 'August' },
{ week: 'Aug 10', signups: 1180, month: 'August' },
{ week: 'Aug 17', signups: 560, month: 'August' },
{ week: 'Aug 24', signups: 540, month: 'August' },
{ week: 'Aug 31', signups: 610, month: 'August' },
]
// Props stay serializable (accessor strings and the default callout): the page is a server component.
export default function WeeklySignups() {
return (
<WaffleColumns
title={meta.title}
description="Weekly signups ran between 380 and 610 except the week of Aug 10, which peaked at 1,180. August brought 3,380 against 1,770 in July."
data={weeks}
x="week"
y="signups"
group="month"
unit={50}
height={216}
/>
)
}
groupTone is a function that picks the tone of each group, here the last quarter, and callout returns your own pill segments. Functions in the props make this a client component.
'use client'
import { WaffleColumns } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'waffle-columns/warranty-claims',
title: 'Warranty claims per month, by quarter',
rscSafe: false,
} satisfies ExampleMeta
const months = [
{ month: 'Jan', claims: 42, quarter: 'Q1' },
{ month: 'Feb', claims: 38, quarter: 'Q1' },
{ month: 'Mar', claims: 51, quarter: 'Q1' },
{ month: 'Apr', claims: 47, quarter: 'Q2' },
{ month: 'May', claims: 55, quarter: 'Q2' },
{ month: 'Jun', claims: 49, quarter: 'Q2' },
{ month: 'Jul', claims: 60, quarter: 'Q3' },
{ month: 'Aug', claims: 66, quarter: 'Q3' },
{ month: 'Sep', claims: 58, quarter: 'Q3' },
{ month: 'Oct', claims: 91, quarter: 'Q4' },
{ month: 'Nov', claims: 84, quarter: 'Q4' },
{ month: 'Dec', claims: 73, quarter: 'Q4' },
]
// 'use client': `groupTone` and `callout` are functions, which a server component cannot pass.
export default function WarrantyClaims() {
return (
<WaffleColumns
title={meta.title}
description="Claims rose every quarter: 131, 151, 184 and 248. October was the peak with 91."
data={months}
x="month"
y="claims"
group="quarter"
groupTone={(group) => (group === 'Q4' ? 'warn' : 'neutral')}
callout={(d) => [{ value: 'Most claims' }, { value: d.month }, { value: `${d.claims}` }]}
unit={5}
height={240}
/>
)
}
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 |
callout | boolean | ((d: D) => readonly TooltipSegment[]) | true | No | Pinned pill over the peak column: true for "Peak | | ", or custom segments. Default true. |
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 | — |
empty | ReactNode | "No data" | No | Rendered instead of the plot when |
format | FormatSpec | 'number' | No | Default 'number'. |
group | Accessor<D, string> | — | No | Group of periods, e.g. the month; labelled under its columns. |
groupTone | (group: string, index: number, groups: readonly string[]) => Tone | the last group 'loss', the others 'neutral' | No | Tone per group. Default: the last group 'loss', the others 'neutral'. |
height | number | 240 unless `aspectRatio` is set | No | Height in px. Default 240 unless |
id | Accessor<D, Id> | the data index | No | Passed to onSelect and onActiveChange. Default: the data index. |
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; |
padding | number | 0.3 | No | Inner band padding, 0–1. Default 0.3. |
peak | boolean | true | No | The largest column solid, the others soft. Default true. |
style | CSSProperties | — | No | — |
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: |
unit | number | a nice step that gives the tallest column about 12 dots | No | Value of one dot. Default: a nice step that gives the tallest column about 12 dots. |
wide | number | 2 | No | Dots across each column. Default 2. |
width | number | — | No | Fixed width in px; turns off container measuring. |
x | Accessor<D, string | number> | — | Yes | Period label, e.g. "Sep 7". |
y | Accessor<D, number> | — | Yes | Value per period. |
Keyboard and screen readers #
WaffleColumns is built on Chart, so it follows the same keyboard model as the other charts: it is a single tab stop, and tabbing in shows the first column with its tooltip and announces it. The points are the periods, in one dimension: ← and → move to the previous or next period. Home and End jump to the first and last point, Enter or Space selects the active point when the chart has onSelect, and Esc clears the active point. Esc is only consumed when a point is active, so an enclosing dialog still closes. The widget’s description ends with a keyboard hint (“Use arrow keys to move between points, Home and End for first and last, Escape to clear.”, plus “Press Enter to select.” with onSelect); keyboardHint replaces it, for example to translate it, and keyboardHint="" turns it off.
Screen readers get the chart title and description, then an announcement for each period the keyboard moves to, in the form “1 of 8, Aug 3, $9.8K”: its position, the period and its value. A visually hidden data table follows the chart with the columns Period and Value (named after the x and y fields when they are strings) and a Group column when group is set. dataTable renames the caption and headers, or turns it off.
The soft dots of columns that are not the peak are decorative and carry no meaning of their own, and the callout pill is aria-hidden, so it says nothing to a screen reader. Put the same facts in the title, the description or the data, as both examples do with the peak.
The full model is in the accessibility guide.