Skip to Content
kindui

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.

Support requests by day and hour
Row / column08:0010:0012:0014:0016:0018:00
Mon12344839278
Tue16425645310
Wed1129No report41246
Thu1847605233No report
Hover a cell, or focus the grid and press the arrow keys, to see its value.

Installation

npx shadcn@latest add @kind-ui/heatmap-chart

Composition

HeatmapChart
├── HeatmapChart.Grid
├── HeatmapChart.Tooltip
├── HeatmapChart.Legend
├── HeatmapChart.DataTable
└── HeatmapChart.Content

HeatmapChart 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:

Contributions by day and week
Row / columnWeek 1Week 2Week 3Week 4Week 5Week 6Week 7Week 8Week 9Week 10Week 11Week 12Week 13Week 14Week 15Week 16Week 17Week 18Week 19Week 20Week 21Week 22Week 23Week 24Week 25Week 26
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Square cells shrink with the page. Hover a cell to see its day and week.

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.