Heatmap

Pro

Activity heatmap in weekly columns or as a calendar month, in four shades of one colour that fill in as a wave. Drag across it to read each day’s value, with a gentle tap per day.

Preview

Installation

npx @lumioui/cli add pro/heatmap

Usage

import { formatHeatmapDate, Heatmap, HeatmapReadout } from "@/components/ui/heatmap/heatmap";
<Heatmap />

Also exported: formatHeatmapDate, HeatmapReadout.

Examples

Commits

A developer profile's commit graph, last 20 weeks in week columns with month labels and a legend.

Focus

A focus timer's history: twelve Monday-first weeks of deep-work hours in large cells, bucketed at 1 · 2.5 · 4 · 5.5 h.

Training

A running app's monthly calendar.

API reference

Heatmap

Prop Type Default
data* HeatmapDatum[] | Record<string, number>

Values per day — an array of { date, value } or a { "2026-09-14": 3 } map.

 —
layout "weeks" | "month"

"weeks" — columns of weeks with month labels; "month" — one calendar month. Default "weeks".

 "weeks"
endDate string

Last day shown in the weeks layout (YYYY-MM-DD). Default today.

 —
weeks number

Week columns in the weeks layout. Default 26.

 26
month string

Month for the month layout, YYYY-MM. Default the month of endDate.

 —
weekStartsOn 0 | 1

0 = Sunday-first rows, 1 = Monday-first. Default 0.

 0
thresholds [number, number, number, number]

Four ascending thresholds for levels 1–4. Default: any activity, then quarters of the max.

 —
color string

Cell colour at full intensity. Default the primary/accent colour.

 —
gap number

Gap between cells. Default 3 (weeks) / 6 (month).

 —
showMonthLabels boolean

Month labels above the week columns. Default true.

 true
showDayLabels boolean

Mon / Wed / Fri labels beside the rows. Default true.

 true
showLegend boolean

"Less ▢▢▢▢▢ More" key under the grid. Default false.

 false
selected string | null

Controlled selected day. null for none.

 —
defaultSelected string | null

Uncontrolled initial selection.

 null
onSelectedChange (date: string | null, value: number) => void

Fires when touch lands on a different day.

 —
accessibilityLabel string

Screen-reader summary. Default "Activity heatmap".

 —
className string —

HeatmapReadout

Prop Type Default
swapKey* string | number | null | undefined

Change this (e.g. the selected date) to swap the readout in place.

 —
className string —