Heatmap
A grid of cells shaded by value, for activity by hour, a year of days, a retention cohort or a change around a baseline. Binned sequential or diverging scales on the validated chart ramps, per grid, row or column; every cell reads out on hover, on focus and to screen readers.
Try it yourself. This one is live, and its code is right below.
Installation#
Usage#
Heatmap is composed from named parts, like Chart. The root takes the data (one array per row), the rows and columns labels and the colour scale. HeatmapGrid draws the cells; HeatmapRowLabels and HeatmapColumnLabels go inside it so they line up with the cells, and HeatmapLegend is the Less / More key.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import {
Heatmap,
HeatmapGrid,
HeatmapRowLabels,
HeatmapColumnLabels,
HeatmapLegend,
CalendarHeatmap,
} from "@/components/ui/heatmap"
<Heatmap>
<HeatmapGrid>
<HeatmapRowLabels />
<HeatmapColumnLabels />
</HeatmapGrid>
<HeatmapLegend />
</Heatmap>
// or, for a run of days:
<CalendarHeatmap data={days} from={from} to={to} />Activity card#
The dashboard widget: one row per event, one column per day, in a Card. Visits and abandonments are a thousand times apart, so each row is shaded against itself (normalize="row"), and the tooltip adds the date the column header leaves out through renderTooltip. Switch the week: the cells tween to their new shades instead of redrawing.
Normalization#
normalize decides what a cell’s shade is measured against. grid (the default) puts every cell on one scale, the honest reading when the rows share a unit and a magnitude. row shades each row from its own quietest cell to its busiest, for rows that differ by orders of magnitude; column does the same down each column. The tooltip and each cell’s accessible name always carry the real number, whatever the shade.
normalize="grid": one scale for every cell: only the visitor rows register
normalize="row": each event against its own quietest and busiest day
normalize="column": each day against itself, event by event
Calendar strip#
A year of days, one column per week. size="sm" tightens the gaps and lowers the cell minimum, so 53 weeks fit a card; on a phone the strip scrolls sideways inside its own box while the day labels stay pinned. null marks the days before the range starts (a blank, not a zero). tickFormatter prints each month once and every other weekday, and cellLabel names each cell by its real date. The legend is a part like any other, so it can share a row with a summary.
969 deploys in the last year
Calendar heatmap#
CalendarHeatmap builds that strip for you from a list of dated readings: pass data as { date, value } entries with from and to, and it lays out the weeks, labels Mon, Wed and Fri and each month over the week it opens, names every cell by its date and, on a narrow screen, opens on the latest weeks. A day with no reading is hatched as No data (here, two days in August when the export failed), so a gap never passes for a quiet day, and the legend keys it. weekStart and locale fit it to the reader.
1,513 commits in the last year
Retention cohort#
The share of each signup cohort still active week by week. Newer cohorts have lived fewer weeks, so the weeks still to come are null and the grid reads as a triangle. domain={[0, 100]} pins the scale to the whole percentage range instead of the data’s own, so a cell’s shade means the same thing in every report, and steps={6} gives the scale more shades to tell the weeks apart.
Diverging scale#
When the story is which side of a baseline a value falls on (warmer or colder, above or below target), use scale="diverging". The cells take the validated chart-div ramp: a blue pole, a red pole and a hueless middle step that reads as no change. The scale is symmetric around midpoint (0 by default), so a degree colder weighs the same as a degree warmer, and the step count is odd so one step straddles the baseline. The legend names both poles by default; here they read Colder and Warmer.
Colors#
With no color, a sequential heatmap takes the validated chart-seq ramp, the house chart scale: one blue hue in binned steps checked for contrast against every theme’s surface, light to dark on light grounds and flipped on dark ones, so the lowest step always sits nearest the surface. Pass a color to tint one hue into the muted track instead, each step adding more of it until the last is the hue at full strength: blue, brand for a heatmap that is the story of the screen, primary, the accents, the status roles, and current for the ambient text colour. Every hue re-themes across light, dark, cream and moonlight.
color="blue"
color="brand"
color="primary"
color="purple"
color="pink"
color="teal"
color="orange"
color="success"
color="warning"
color="info"
color="destructive"
color="current" + text-foreground
Steps#
steps sets how many shades sit above the empty track (four by default). The ramp goes up to seven, past which neighbouring steps blur; a color tint goes up to ten. Fewer steps read faster and hide small differences; more steps show them. The legend always paints the scale the grid uses, and pointing at a swatch dims every cell outside that step.
steps={3}
steps={4} (default)
steps={7}
Size#
Cells always share the width of the box, down to a minimum. md (the default) keeps them at least 24px with 4px gaps, room for a three-letter label over every column in a dashboard card; sm goes down to 10px with 2px gaps, for a dense strip. Below the minimum the grid scrolls sideways inside its own box, never the page.
size="md" (default)
size="sm"
Aspect#
Cells are square by default, so a many-column grid keeps its proportions. aspect="wide" holds one row height (28px at md, 12px at sm) and lets the cells stretch across their column, for a few columns in a lot of width, where squares would make a tower.
aspect="square" (default)
aspect="wide"
Only the parts you need#
Every part is optional. Leave out the legend for a tight card, or the labels too for a bare strip beside a figure: the grid takes back the room they would have used, with no gutter left behind. The tooltip is a render prop on HeatmapGrid; return null to go without one.
Legend dropped
Labels and legend dropped: a bare strip
Tooltips dropped: renderTooltip returns null
Load animation#
Like the Chart, a heatmap plays a one-shot reveal when it mounts: the cells fade and grow in a diagonal wave from the top-left corner. It never replays on hover or when the data changes (a changed cell tweens its shade instead), and it holds still under prefers-reduced-motion. Pass animate={false} to opt out. Press Replay to watch it again.
Empty state#
With no rows or no columns, HeatmapGrid shows a muted message in place of the cells and the labels and legend step aside. Pass empty on the root to say something more useful. A grid of zeros is not empty: it paints the muted track, which is the truth.
Default
Custom message
Accessibility#
The cells are an ARIA grid named by label. It is one tab stop: the arrow keys move between cells (skipping blanks), Home and End jump to the ends of a row, and Ctrl+Home and Ctrl+End to the first and last cell; a hatched No data cell is a stop too. Focus opens the same tooltip as hover. Every cell carries its full reading as its name (“Sign-ups, Mon: 131”), so the row and column labels are decorative duplicates hidden from assistive tech. The legend is an image named by a summary of its scale (“Colour scale: 4 steps from 0 to 182”). Write a cellLabel when the labels alone do not say what a cell is, like a calendar day.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
API reference#
Heatmap
The root: owns the data, the labels and the colour scale, and shares them with the parts through Context. Forwards all native <div> props except color; every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| data* | ReadonlyArray<ReadonlyArray<number | null | undefined>> | - | One array per row, one entry per column. null, a missing entry or a non-finite number is a blank cell; zero paints the muted track. |
| rows | readonly string[] | - | Row labels, in order; used by HeatmapRowLabels, the tooltips and each cell's name. Missing ones read Row 1, Row 2... |
| columns | readonly string[] | - | Column labels, in order; missing ones read Column 1, Column 2... Its length also sets the minimum column count. |
| normalize | "grid" | "row" | "column" | "grid" | What each shade is measured against: the whole grid, its own row, or its own column. |
| domain | readonly [number, number] | - | Pin the scale to [low, high] (say [0, 100] for percentages); normalize then has no effect. |
| scale | "sequential" | "diverging" | "sequential" | sequential encodes magnitude (zero paints the muted track). diverging encodes polarity around midpoint on the chart-div ramp, symmetric so equal distances weigh the same on both arms; its middle step is the hueless div-4. |
| midpoint | number | 0 | The diverging baseline: the value that reads as neutral. |
| steps | number | 4 (sequential), 5 (diverging) | Sequential: steps above the track, 1 to 7 on the ramp (1 to 10 with a color tint). Diverging: 3, 5 or 7 (an even count rounds up). |
| color | "blue" | "brand" | "primary" | "purple" | "pink" | "teal" | "orange" | "success" | "warning" | "info" | "destructive" | "current" | - | Sequential only. Omit it for the validated chart-seq ramp; pass a hue to tint it into the muted track instead (current takes the ambient text colour). |
| missing | "blank" | "hatch" | "blank" | How a null reads. blank: an empty slot with no focus or tooltip. hatch: a hatched, focusable "No data" cell, keyed in the legend; undefined or a short row stays blank. |
| missingLabel | string | "No data" | What a hatched cell is called in its tooltip, its accessible name and the legend. |
| size | "sm" | "md" | "md" | md: cells at least 24px, 4px apart. sm: at least 10px, 2px apart, for a dense strip. |
| aspect | "square" | "wide" | "square" | wide keeps one row height (28px at md, 12px at sm) and stretches cells across their column. |
| valueFormatter | (value: number) => string | - | Formats a value for the tooltip and each cell's name; defaults to en-US grouping with up to two decimals. |
| label | string | - | Accessible name of the grid, for example "Events per day, Sep 21 to Sep 27". Strongly recommended. |
| animate | boolean | true | Play the one-shot diagonal reveal on mount; held still under prefers-reduced-motion. |
| empty | ReactNode | "No data to display" | Shown in place of the cells when data has no rows or no columns. |
| Data attribute | Description |
|---|---|
| data-size | "sm" or "md". |
| data-aspect | "square" or "wide". |
| data-scale | "sequential" or "diverging". |
| CSS variable | Description |
|---|---|
| --heatmap-color | The tint's hue, set by color; override it for a hue outside the list. |
HeatmapGrid
The scroll box and the ARIA grid of cells, with one shared tooltip that glides between them. Holds HeatmapRowLabels and HeatmapColumnLabels; forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| renderTooltip | (cell: HeatmapCell) => ReactNode | - | The tooltip body for a cell, composed from the Tooltip graph parts; return null for no tooltip. Defaults to row label, column label and the formatted value. |
| cellLabel | (cell: HeatmapCell) => string | - | Each cell's accessible name. Defaults to "row, column: value" ("Sign-ups, Mon: 131"). |
| initialScroll | "start" | "end" | "start" | Where a grid wider than its box opens; end shows the latest columns of a timeline first. |
| Data attribute | Description |
|---|---|
| data-row | On each cell: its row index, from 0. |
| data-column | On each cell: its column index, from 0. |
| data-level | On each cell with a value: its scale step, 0 (the track) to steps on a sequential scale, 1 to steps on a diverging one. |
| data-blank | On each empty slot. |
| data-missing | On each hatched "No data" cell (missing="hatch"). |
| data-dimmed | On each cell outside the legend step under the pointer. |
| CSS variable | Description |
|---|---|
| --heatmap-alpha | Per cell, with a color tint: the share of the hue mixed into the muted track, as a percentage. |
| --heatmap-cell-min | The narrowest a column gets before the grid scrolls (set by size). |
| --heatmap-rows | Row count, set inline on the layout. |
| --heatmap-columns | Column count, set inline on the layout. |
HeatmapRowLabels
The labels down the start edge, pinned while a wide grid scrolls; place it inside HeatmapGrid. Hidden from assistive tech, painted on --surface (falling back to --background); forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| tickFormatter | (label: string, index: number) => ReactNode | - | Format a label, or return null to leave its slot empty. |
| interval | number | 1 | Show every Nth label only, to thin out a crowded axis. |
| Data attribute | Description |
|---|---|
| data-active | On the label of the hovered or focused cell's row. |
HeatmapColumnLabels
The labels across the top; place it inside HeatmapGrid. A label followed by an empty slot spills from its column's start edge. Hidden from assistive tech; forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| tickFormatter | (label: string, index: number) => ReactNode | - | Format a label, or return null to leave its slot empty. |
| interval | number | 1 | Show every Nth label only, to thin out a crowded axis. |
| Data attribute | Description |
|---|---|
| data-active | On the label of the hovered or focused cell's column. |
| data-spill | On a label whose next slot is empty, so it marks its column from the start edge. |
HeatmapLegend
One swatch per step of the scale, plus a hatched "No data" key when a reading is missing. Pointing at a swatch dims every cell outside that step. Exposed as an image named by a summary of the scale; forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| lowLabel | ReactNode | "Less", or the low pole when diverging | Before the scale; null drops it. |
| highLabel | ReactNode | "More", or the high pole when diverging | After the scale; null drops it. |
| emptyLabel | ReactNode | the root's missingLabel | Beside the hatched swatch, shown only when a reading is missing; null drops the key. |
| Data attribute | Description |
|---|---|
| data-level | On each swatch: its step. |
| data-missing | On the hatched swatch. |
| data-dimmed | On each swatch other than the one under the pointer. |
CalendarHeatmap
A ready-made day-by-day heatmap composed from the parts above: one column per week, one row per weekday (Mon, Wed and Fri labelled), month names over the weeks they open, and the latest weeks in view on a narrow screen. A day in range with no entry or a null is hatched as no data; the slots around the range are blank. Takes the root's scale props (scale, domain, midpoint, steps, color, valueFormatter, label) and size, sm by default.
| Prop | Type | Default | Description |
|---|---|---|---|
| data* | ReadonlyArray<{ date: string | Date; value: number | null }> | - | One entry per day. An ISO string is read as the day it names, with no time zone shift. |
| from* | Date | - | The first day shown. |
| to* | Date | - | The last day shown. |
| weekStart | 0 | 1 | 1 | The first row of each week: 0 for Sunday, 1 for Monday. |
| locale | string | "en-US" | BCP 47 locale for the month, weekday and date labels. |
| legend | boolean | true | Render a HeatmapLegend under the grid; pass false and compose your own as a child. |
| renderTooltip | (day: CalendarHeatmapDay) => ReactNode | - | The tooltip body for a day: the cell plus its date. Defaults to the formatted value over the long date. |
| cellLabel | (day: CalendarHeatmapDay) => string | - | Each day's accessible name. Defaults to "Wed, Jan 1, 2025: 3 commits". |
| Data attribute | Description |
|---|---|
| data-calendar | On the root, to tell a calendar from a plain heatmap. |