Calendar heatmaps for activity over time
Make a year of daily activity readable at a glance, from GitHub contributions to publishing streaks.
- Rows
- Day of the week
- Columns
- Calendar week
- Value
- Daily contributions
The pattern
What the data tells you
Weekday streaks and quiet weekends stand out. Three unobserved days remain distinct from zero activity.
A calendar heatmap puts the date on the x-axis and lets colour carry intensity. It is the right default when people need to spot streaks, quiet periods, seasonality, and one-off spikes without opening a report.
Calendar grids work because the shape is familiar. Readers can scan month boundaries, compare weekdays, and hover a single day for detail without learning a new chart. heatmap-ui keeps that structure headless, so the same visual can sit inside a dashboard, profile, or product surface.
Build it in React
From data to heatmap
Prepare your data
One dated value per day. Add known: false when a source did not observe a day so missing data never reads as zero activity.
Make the component yours
Start with this example. Adjust the labels, colours, and tooltips to fit your product.
import { CalendarHeatmap, type CalendarDay } from "@thilakbhat/heatmap-ui";
import "@thilakbhat/heatmap-ui/styles.css";
const days: CalendarDay[] = [
{ date: "2026-09-09", value: 0, known: false }, // not observed, not zero
{ date: "2026-09-10", value: 4 },
{ date: "2026-09-11", value: 9 },
{ date: "2026-09-12", value: 2 },
];
export function ActivityCalendar() {
return (
<CalendarHeatmap
values={days}
to="2026-09-12"
weeks="auto" // as many weeks as the container fits, up to a year
showMonthLabels
showWeekdayLabels
showLegend
unitLabel="events"
/>
);
}A few more details
Common questions
Calendar heatmaps, explained.
What is a calendar heatmap used for?
A calendar heatmap shows one value per day so readers can spot streaks, quiet periods, seasonality, and unusual spikes across weeks or a full year.
How do I build a calendar heatmap in React?
Pass an array of dated values such as { date: "2026-09-12", value: 9 } to heatmap-ui's CalendarHeatmap component, then configure the visible weeks, labels, legend, and unit text.
How should missing days be represented in a calendar heatmap?
Mark an unobserved day with known: false instead of value: 0. That keeps missing data visually distinct from a day with confirmed zero activity.
Can a calendar heatmap visualize GitHub contributions?
Yes. Map each GitHub contribution day to the calendar shape with its date and contribution count, then render the result with CalendarHeatmap or the GitHub graph page in this site.