Heat Table

A grid of values shaded by size.

Source
$npx @dinachi/cli@latest add heat-table

Week 1 return rose from 52% to 56%

Weekly cohorts since 14 Sep

CohortW1W2W3W4W5W6W7W8W9
14 Sep, 1,334
21 Sep, 1,370
28 Sep, 1,188
5 Oct, 1,241
12 Oct, 1,256
Average54%47%41%36%30%26%23%19%16%
52%
618 of 1,188 came back in week 1
Joined the week of 28 Sep
format
min
footer

Usage

import { HeatTable } from "@/components/ui/heat-table"

const cohorts = [
  { label: "14 Sep", meta: "1,334", values: [52, 45, 37] },
  { label: "21 Sep", meta: "1,370", values: [56, 48] },
  { label: "28 Sep", meta: "1,188", values: [52] },
]

export function Retention() {
  return (
    <HeatTable
      aria-label="Weekly return by cohort"
      columns={["W1", "W2", "W3"]}
      rows={cohorts}
      rowHeader="Cohort"
      format={(v) => `${v}%`}
    />
  )
}

Examples

Week 1 return rose from 52% to 61%

Weekly cohorts since 14 Sep

CohortW1W2W3W4W5W6W7W8W9
14 Sep, 1,334
21 Sep, 1,370
28 Sep, 1,188
5 Oct, 1,241
12 Oct, 1,256
19 Oct, 1,392
26 Oct, 1,205
2 Nov, 1,034
9 Nov, 929
Average56%48%41%35%30%26%23%19%16%
52%
618 of 1,188 came back in week 1
Joined the week of 28 Sep
Nine weekly cohorts shaded by the share that came back each week, with the average under them.
import { HeatTable } from '@/components/ui/heat-table';

const cohorts = [
  { label: '14 Sep', size: 1334, meta: '1,334', values: [52, 45, 37, 36, 27, 26, 23, 18, 16] },
  { label: '21 Sep', size: 1370, meta: '1,370', values: [56, 48, 43, 35, 29, 24, 25, 19] },
  { label: '28 Sep', size: 1188, meta: '1,188', values: [52, 44, 42, 36, 28, 25, 22] },
  // ...one row per weekly cohort
];

const weeks = ['W1', 'W2', 'W3', 'W4', 'W5', 'W6', 'W7', 'W8', 'W9'];

export function Example() {
  return (
    <HeatTable
      aria-label="Weekly return by cohort"
      columns={weeks}
      phoneColumns={weeks.map((_, w) => String(w + 1))}
      rows={cohorts}
      rowHeader="Cohort"
      format={(v) => `${v}%`}
      label={(c) => `${c.row.label} cohort, week ${c.columnIndex + 1}: ${c.value}%`}
      footer={{ label: 'Average', values: ['56%', '48%', '41%', '35%', '30%', '26%', '23%', '19%', '16%'] }}
    />
  );
}

Notes

One fact per shade

A cell's shade is the primary colour mixed into the surface by its place between min and max. Past the middle the text turns to the primary foreground, and the mix skips the band where neither text colour would reach 4.5:1. Use heatShade(amount) to shade a legend the same way.

Blank cells

A null value leaves its cell empty and out of the keyboard path, which gives cohort data its stair edge.

Phone

Below 768px the grid keeps its shape as squares with no numbers. Up to 12 columns share the width; past that each square keeps 28px and the grid scrolls sideways. Tapping a square rings it and fills the readout under the grid.

Large grids

Pointing at a cell lights its headers without rendering the grid again, and choosing a cell draws only the two rows it touches. For hundreds of rows set maxHeight and virtualize, so only the rows in view are in the page.

API

columnsstring[]
The column names as printed, such as W1 to W9.
columnLabelsstring[]
Each column's full name for screen readers and the default cell name, such as Wed 18 Nov 2026 over a printed 18. Defaults to columns.
columnGroups{ label, span }[]
A header row over the columns, each group spanning span columns, such as months over days.
phoneColumnsstring[]
Shorter column names below 768px, where each column is a narrow square. Defaults to columns.
rowsHeatRow[]
Each row: a label, optional meta shown after it on desktop, and values with one number per column. null leaves a cell blank.
rowHeaderReactNode
The name over the row labels, such as Cohort.
format(value, cell) => string
A value as printed. The shade follows the value, not the printed text.
label(cell) => string
A cell's accessible name. Defaults to the row, the column and the printed value.
minnumber
The value that shades lightest. Defaults to the lowest value.
maxnumber
The value that shades darkest. Defaults to the highest value.
scale(value, { min, max }) => number
Maps a value to 0 to 1. Defaults to a straight line from min to max.
footer{ label, values }
A summary row under the grid, such as the average. Hidden on a phone.
readout(cell) => ReactNode
What the line under the grid says about the chosen square on a phone. Defaults to the value, then the row and column.
defaultCell{ row, column }
The cell chosen at first, which holds the tab stop and fills the phone readout. Defaults to the first filled cell.
density"comfortable" | "compact" = "comfortable"
Cell size: 56 by 38px, or 32 by 26px. Set --heat-table-cell-width and --heat-table-cell-height for any other size.
maxHeightnumber
Height of the scrolling area in px. Virtualized grids default to 480.
virtualizeboolean = false
Renders only the rows in view, for grids of thousands of rows.
stickyboolean
Keeps the column headers and row labels in view as the grid scrolls. On once maxHeight is set. Sticky cells take --heat-table-surface, which defaults to --background.
onCellHover(cell | null) => void
Runs as the pointer enters a filled cell, and with null as it leaves the grid.
onCellFocus(cell) => void
Runs when a cell takes focus, by keyboard or click.
onCellClick(cell, event) => void
Runs when a filled cell is clicked.
containerClassNamestring
Class for the element that scrolls the grid.
containerRefRef<HTMLDivElement>
The element that scrolls the grid.

Accessibility

  • An ARIA grid with one tab stop. Arrows move between cells, so the page's tab order passes it in one step.
  • Each cell is named by its row, its column and its value, so a screen reader never has to work out the headers. columnLabels gives short printed columns a full spoken name.
  • The chosen cell carries aria-selected.
  • The number is always printed on desktop, and named on every cell, so the shade is never the only signal.
  • The phone readout is a polite live region, so tapping a square says what it holds.
  • The lit row and column headers take a tint as well as the text colour, so they show even where muted text sits close to the foreground.
  • Hover and focus rings respect reduced motion.