Charts
Heatmap
Two categories and one value, as a grid of shaded cells. Rows and columns are the categories, and the shade of a cell is the bin its value falls in, so the biggest numbers stand out at a glance.
When to use it #
Use Heatmap when every combination of two categories has a value and you want to see where the high ones cluster: cost by branch and cause, pages by team and shift, tickets by day and category. You pick the bins with breaks (1 to 4 edges give 2 to 5 bins), and each cell keeps its number as text, so the shade never carries the value alone. With totals (on by default) a row and a column of sums frame the grid.
The shades come from the same bins as the thresholds page describes, and a Legend can show them next to other charts. If you only have one category, use BarChart: bars compare a single row of values more precisely than shades.
Import #
npm i tally-chartsimport { Heatmap } from 'tally-charts'
import 'tally-charts/theme.css'Examples #
Data in long format, one item per cell. rows and columns fix the order, rowLabel names the row header column, and binLabels names the four bins. Every prop is serializable, so this is a server component.
- Under 5
- 5 to 9
- 10 to 19
- 20 and up
import { Heatmap } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'heatmap/on-call-pages',
title: 'On-call pages by team and shift',
rscSafe: true,
} satisfies ExampleMeta
const shifts = ['Night', 'Morning', 'Afternoon', 'Evening']
const pages: Record<string, number[]> = {
Platform: [14, 6, 9, 21],
Payments: [3, 8, 12, 17],
Search: [2, 5, 7, 4],
Mobile: [9, 11, 6, 13],
Data: [1, 2, 3, 2],
}
const data = Object.entries(pages).flatMap(([team, counts]) =>
counts.map((count, i) => ({ team, shift: shifts[i] ?? '', count })),
)
// Props stay serializable (no functions): the page is a server component.
export default function OnCallPages() {
return (
<Heatmap
title={meta.title}
description="Evening is the busiest shift with 57 of 155 pages; Platform's evening alone is 21."
data={data}
row="team"
column="shift"
value="count"
rows={Object.keys(pages)}
columns={shifts}
rowLabel="Team"
breaks={[5, 10, 20]}
binLabels={['Under 5', '5 to 9', '10 to 19', '20 and up']}
format="number"
/>
)
}
Conversion rates do not add up, so totals={false} drops the sums. A missing cell (Events has no Starter trials) reads “No data” and is drawn as a dashed empty cell. onSelect and the selected cell in state make this a client component.
'use client'
import { useState } from 'react'
import { Heatmap, type HeatmapCell } from 'tally-charts'
import type { ExampleMeta } from '../types'
export const meta = {
id: 'heatmap/trial-conversion',
title: 'Trial-to-paid conversion by channel and plan',
rscSafe: false,
} satisfies ExampleMeta
const plans = ['Starter', 'Pro', 'Team', 'Enterprise']
// Percent of trials that became paid. Events has no Starter trials: that cell is missing.
const rates: Record<string, (number | null)[]> = {
Search: [4.1, 6.8, 9.2, 11.5],
Referral: [5.3, 8.4, 12.7, 14.9],
Newsletter: [3.2, 5.1, 7.4, 6.0],
Social: [1.8, 2.6, 3.1, 2.2],
Events: [null, 7.9, 10.8, 18.3],
}
const data = Object.entries(rates).flatMap(([channel, values]) =>
values.flatMap((rate, i) => (rate === null ? [] : [{ channel, plan: plans[i] ?? '', rate }])),
)
// 'use client': `onSelect` is a function and the selected cell is state.
export default function TrialConversion() {
const [selected, setSelected] = useState<HeatmapCell<(typeof data)[number]> | null>(null)
return (
<div style={{ display: 'grid', gap: '0.75rem' }}>
<Heatmap
title={meta.title}
description="Events convert best on Enterprise at 18.3%; Social never passes 3.1%."
data={data}
row="channel"
column="plan"
value="rate"
columns={plans}
// Rates do not add up, so the totals are off.
totals={false}
breaks={[3, 6, 10]}
format={{ preset: 'percent', digits: 1 }}
tone="accent"
onSelect={(_id, cell) => setSelected(cell)}
/>
<p aria-live="polite" style={{ margin: 0 }}>
{selected
? `Selected: ${selected.row}, ${selected.column}, ${selected.value.toFixed(1)}%`
: 'Select a cell to read it here.'}
</p>
</div>
)
}
Columns never get narrower than their name or --ch-heatmap-min-cell; below that the grid scrolls sideways.
Props #
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
activeId | string | null | — | No | — |
aria-labelledby | string | — | No | Id of an element that names the chart; it wins over |
binLabels | readonly string[] | "Under X", "X to Y", …, "Z and up" | No | One label per bin. Default "Under X", "X to Y", …, "Z and up". |
breaks | readonly number[] | — | Yes | Ascending bin edges: values below |
chartId | string | — | No | Prefix for the title and description ids. React's |
className | string | — | No | — |
column | Accessor<D, string> | — | Yes | Column name per item, e.g. the cause. |
columns | readonly string[] | order of first appearance | No | Column order. Default: order of first appearance. |
data | readonly D[] | — | Yes | One item per cell, in long format. |
description | string | — | No | Accessible description, usually the takeaway sentence. |
empty | ReactNode | "No data" | No | Rendered instead of the grid when there are no rows or columns. Default "No data". |
format | FormatSpec | 'number' | No | Default 'number'. |
legend | boolean | true | No | Legend of the bins under the grid. Default true. |
onActiveChange | (id: string | null, cell: HeatmapCell<D> | null) => void | — | No | — |
onSelect | (id: string, cell: HeatmapCell<D>) => void | — | No | — |
row | Accessor<D, string> | — | Yes | Row name per item, e.g. the branch. |
rowLabel | string | the `row` field name in sentence case ("branch" reads "Branch"), or "Row" for a function | No | Accessible name of the row header column (the empty corner above it). Default: the |
rows | readonly string[] | order of first appearance | No | Row order. Default: order of first appearance. Rows without items show dashes. |
style | CSSProperties | — | No | — |
title | string | — | No | Accessible name of the chart; also the default caption of the data table. |
tone | Tone | a `--ch-seq-base` set on an ancestor, else loss | No | Base tone of the sequential levels and the legend. Default: a |
totalLabel | string | "Total" | No | Header of the row total column and of the column totals row. Default "Total". |
totals | boolean | true | No | Column totals under the headers and a row total column. Default true. |
value | Accessor<D, number> | — | Yes | — |
Keyboard and screen readers #
Heatmap is an ARIA grid, not a Chart, with one tab stop: a roving tabindex that sits on the first data cell until another cell has had focus. Arrow keys move one cell, Home and End go to the start and end of the row, Ctrl+Home and Ctrl+End (or Cmd) to the first and last cell of the grid, and PageUp and PageDown move five rows. Enter or Space selects a data cell when the heatmap has onSelect. Esc clears the active cell, and only when one is active.
The row of column totals and the column of row totals are cells too: arrow keys reach them, and focusing one clears the active cell. Enter does nothing on a total. Turn them off with totals={false}.
In a container too narrow for the columns, the grid scrolls sideways inside a role="group" named after the title (“Heatmap” without one). That group becomes a tab stop of its own so that keyboard users can scroll it, which makes two tab stops: the scroll region first, then the grid. The page itself does not scroll sideways.
Screen readers get a grid named by title (or aria-labelledby) and described by description. The first row holds the column headers: the corner, named by rowLabel (by default the row field in sentence case), the column names and, with totals, a “Total” header (totalLabel). With totals, the next row holds the column totals, headed by totalLabel, and ends with the grand total. Every data row starts with its row header and, with totals, ends with its total. A cell reads as its value with its row and column header, such as “Dallas, Labor, $14.8K”, and a missing value reads “No data”.
The full model is in the accessibility guide.