Heatmap
Compare a value across two sets of categories with a grid of colored cells.
Use a heatmap to show how one measure varies across two ordered sets, like days and hours, when the pattern matters more than each exact value.
| Row / column | 08:00 | 10:00 | 12:00 | 14:00 | 16:00 | 18:00 |
|---|---|---|---|---|---|---|
| Mon | 12 | 34 | 48 | 39 | 27 | 8 |
| Tue | 16 | 42 | 56 | 45 | 31 | 0 |
| Wed | 11 | 29 | No report | 41 | 24 | 6 |
| Thu | 18 | 47 | 60 | 52 | 33 | No report |
Installation
npx shadcn@latest add @kind-ui/heatmap-chartComposition
HeatmapChart
├── HeatmapChart.Grid
├── HeatmapChart.Tooltip
├── HeatmapChart.Legend
├── HeatmapChart.DataTable
└── HeatmapChart.ContentHeatmapChart holds the rows, columns, data and color scale, and draws only the parts you add. The grid is an HTML table with a header for each row and column, so screen readers can read it like one. Heatmaps have no series, so pass config={{}}. HeatmapChart.Content places your own HTML next to the legend.
Usage
Rows, Columns and Data
rows and columns set the order of the grid. data has one { row, column, value } record per cell; a record whose row or column isn't listed throws. A missing record or a null value shows as a patterned cell labeled missingLabel, while 0 is a measured value. When two records share a cell, duplicates decides what happens: error (the default), first, last or sum.
formatValue formats the value in the cells, tooltip and legend, like (value) => `${value}%` , without changing the colors.
Color Scale
createHeatmapScale maps a numeric domain to two or more #rrggbb colors, spaced evenly. Values outside the domain take the nearest end color. For values above and below a target, center the domain on zero with a neutral middle color:
const scale = createHeatmapScale({
domain: [-20, 20],
colors: ["#9a3412", "#fff7ed", "#1e40af"],
});Keep the same scale when you compare two heatmaps, so the same color means the same value. HeatmapChart.Legend shows the scale's ends, zero for a domain that crosses it, and the missing-cell swatch.
Compact Grids
Set layout on the grid for fixed square cells: cellSize, gap, and rowLabels or columnLabels set to hidden. Hidden labels stay readable by screen readers, and the tooltip still names each cell. Pass Cell to change what each cell shows, like nothing:
| Row / column | Week 1 | Week 2 | Week 3 | Week 4 | Week 5 | Week 6 | Week 7 | Week 8 | Week 9 | Week 10 | Week 11 | Week 12 | Week 13 | Week 14 | Week 15 | Week 16 | Week 17 | Week 18 | Week 19 | Week 20 | Week 21 | Week 22 | Week 23 | Week 24 | Week 25 | Week 26 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mon | ||||||||||||||||||||||||||
| Tue | ||||||||||||||||||||||||||
| Wed | ||||||||||||||||||||||||||
| Thu | ||||||||||||||||||||||||||
| Fri | ||||||||||||||||||||||||||
| Sat | ||||||||||||||||||||||||||
| Sun |
Set material="clay" or "glow" on the grid for a finish on the cell edges; see Materials.
Keyboard
Focus the grid and press the arrow keys to move between cells, which shows the tooltip. Home and End go to the ends of a row, Ctrl+Home and Ctrl+End to the first and last cells, and Escape dismisses the tooltip. Pass valueAnimation="shuffle" to the tooltip to animate its digits.
Motion
Pass animate to fade the cells in diagonally when the chart mounts. Heatmaps don't animate by default. When the reader prefers reduced motion, cells appear without fading in. See Motion.
Loading
Set loading while the data is on its way. The chart shows a placeholder grid, which holds still when the reader prefers reduced motion. Screen readers hear loadingLabel ("Loading chart" by default):
<HeatmapChart loading={isPending} loadingLabel="Loading requests" {...props}>API Reference
HeatmapChart
Prop
Type
HeatmapChart.Grid
Prop
Type
HeatmapChart.Tooltip
Prop
Type
HeatmapChart.Legend
Prop
Type
createHeatmapScale
Prop
Type
HeatmapChart.DataTable takes a caption and shows the same records as a plain table. Each part also takes the props of its HTML element, like className and style.