Calendar Heatmap

A year of daily values as week columns — the contributions grid, with five quantised intensity steps, streak stats, and month rails.

A year of activity

@spectrumui/calendar-heatmap

1.6K contributions

7 day current streak · 13 day longest

LessMore

Deploys

1.7K deploys

3 day current streak · 14 day longest

LessMore

Manual installation

Prefer to copy by hand? Open the Code tab on any example above and switch to the file you need — every source file is there, not just the demo. Drop them in your project like this:

chart-engine.tsxcomponents/spectrumui/charts/chart-engine.tsx
calendar-heatmap.tsxcomponents/spectrumui/charts/calendar-heatmap.tsx

There is nothing to install — this chart draws its own SVG and imports only @/lib/utils.

Usage

import { CalendarHeatmap } from '@/components/spectrumui/charts/calendar-heatmap';

<CalendarHeatmap data={days} label="contributions" />

Days need { t, value } with t at UTC midnight; gaps are filled as zero.
Intensity is quantised into five buckets — the eye cannot rank a continuous ramp.

Props

Prop	Type	Default	Description
`data`	`CalendarDay[]`	`CONTRIBUTIONS`	One { t, value } per day, oldest first.
`cell`	`number`	`13`	Cell edge in pixels. Cells shrink below this to fit narrow containers.
`label`	`string`	`'contributions'`	Noun used in the total and the hover readout.
`hue`	`string`	`series-3`	CSS colour for the intensity ramp.
`status`	`'ready' \| 'loading' \| 'empty' \| 'error'`	`'ready'`	Which state to render. All four reserve the same frame height, so nothing shifts when data lands.
`onRetry`	`() => void`	-	Called by the retry button in the error state. Omit it and no button is shown.
`className`	`string`	-	Merged onto the root element.