On this page

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 #

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

On-call pages by team and shift
View of On-call pages by team and shift
Team
Night
Morning
Afternoon
Evening
Total
Total
29
32
37
57
155
Platform
14
6
9
21
50
Payments
3
8
12
17
40
Search
2
5
7
4
18
Mobile
9
11
6
13
39
Data
1
2
3
2
8
  • Under 5
  • 5 to 9
  • 10 to 19
  • 20 and up

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.

Trial-to-paid conversion by channel and plan
View of Trial-to-paid conversion by channel and plan

Columns never get narrower than their name or --ch-heatmap-min-cell; below that the grid scrolls sideways.

Props #

NameTypeDefaultRequiredDescription
activeIdstring | null—No—
aria-labelledbystring—No

Id of an element that names the chart; it wins over title for the name.

binLabelsreadonly string[]"Under X", "X to Y", …, "Z and up"No

One label per bin. Default "Under X", "X to Y", …, "Z and up".

breaksreadonly number[]—Yes

Ascending bin edges: values below breaks[0] are the first bin. 1–4 edges give 2–5 bins.

chartIdstring—No

Prefix for the title and description ids. React's useId is only unique within one root, so set this when heatmaps render in several React roots on one page.

classNamestring—No—
columnAccessor<D, string>—Yes

Column name per item, e.g. the cause.

columnsreadonly string[]order of first appearanceNo

Column order. Default: order of first appearance.

datareadonly D[]—Yes

One item per cell, in long format.

descriptionstring—No

Accessible description, usually the takeaway sentence.

emptyReactNode"No data"No

Rendered instead of the grid when there are no rows or columns. Default "No data".

formatFormatSpec'number'No

Default 'number'.

legendbooleantrueNo

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—
rowAccessor<D, string>—Yes

Row name per item, e.g. the branch.

rowLabelstringthe `row` field name in sentence case ("branch" reads "Branch"), or "Row" for a functionNo

Accessible name of the row header column (the empty corner above it). Default: the row field name in sentence case ("branch" reads "Branch"), or "Row" for a function.

rowsreadonly string[]order of first appearanceNo

Row order. Default: order of first appearance. Rows without items show dashes.

styleCSSProperties—No—
titlestring—No

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

toneTonea `--ch-seq-base` set on an ancestor, else lossNo

Base tone of the sequential levels and the legend. Default: a --ch-seq-base set on an ancestor, else loss. Every tone keeps cell text at 4.5:1 or more in both themes.

totalLabelstring"Total"No

Header of the row total column and of the column totals row. Default "Total".

totalsbooleantrueNo

Column totals under the headers and a row total column. Default true.

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