Calendar Heatmap
A colour-coded grid of calendar days that reveals daily, weekly, and seasonal patterns in a single numeric variable — made famous by GitHub’s contribution graph.
// 01 — The chart
What it looks like
A calendar heatmap showing daily step counts. Darker cells indicate higher activity; the weekly structure reveals day-of-week patterns.
// 02 — Definition
What is a calendar heatmap?
A calendar heatmap is a grid of small coloured cells, one per day, arranged in a calendar layout with weeks as columns and days of the week as rows. Colour intensity encodes the magnitude of a single numeric variable for each day.
The most famous example is GitHub’s contribution graph, which shows how many commits a developer made each day. But the format works for anything measured daily: sales, website traffic, exercise, temperature, air quality, and more.
What makes calendar heatmaps special is that they preserve the natural structure of the calendar. You can instantly see that activity drops every weekend, or that there’s a seasonal peak in Q4. No other chart type reveals daily + weekly + seasonal patterns simultaneously.
Ubiquity: GitHub popularised this format around 2013. Today it appears in fitness apps, productivity trackers, and editorial data journalism pieces worldwide.
// 03 — Anatomy
Parts of a calendar heatmap
// 04 — Usage
When to use it — and when not to
- Showing daily activity or frequency across a full year
- You want to reveal day-of-week and seasonal patterns simultaneously
- Tracking personal metrics: exercise, commits, habits, mood
- Comparing year-over-year activity levels
- Your data has exactly one numeric value per day
- You need to show precise values — colour intensity is hard to decode
- Your data has sub-daily resolution (use a line chart instead)
- You have multiple variables per day — heatmaps encode only one
- The calendar structure adds no insight (random, non-temporal data)
- Data spans less than a month — the grid looks sparse and uninformative
// 05 — Reading guide
How to read a calendar heatmap
Understand the colour scale
Check the legend. Lighter cells usually mean lower values; darker cells mean higher values. Some use green (GitHub) while others use sequential colour ramps.
Scan for day-of-week patterns
Look across each row. If certain rows are consistently darker (e.g. weekdays), you've found a weekly rhythm in the data.
Look for seasonal trends
Scan from left to right. Are there stretches of darker or lighter cells? These reveal monthly or seasonal patterns.
Spot outliers
Individual very dark or very light cells stand out against their neighbours. These are unusual days worth investigating.
Compare years side by side
When multiple years are shown vertically, compare the same months across years to spot growth, decline, or recurring patterns.
// 06 — Data format
What data you need
Two columns: a date and a numeric value. One row per day. Missing days are rendered as empty cells. The date column must be parseable (ISO 8601 is ideal).
// 07 — Construction
How to build one
Step 1: Determine the date range and compute the day-of-week and week-of-year for each date.
Step 2: Create a grid where rows are days of the week (0–6) and columns are weeks of the year.
Step 3: Map values to a sequential colour scale (e.g. white → dark green, or light → dark red).
Step 4: Add month labels at column boundaries and day-of-week labels on the left. Include a colour legend.
// 08 — Common mistakes
Mistakes to avoid
Using too many colour steps
Humans can distinguish about 5–7 levels of colour intensity. More than that and adjacent levels become indistinguishable.
Missing colour legend
Without a legend mapping colours to values, the heatmap is just a pretty grid. Always include one.
Comparing across different scales
If you show two years side by side, both must use the same colour scale. Otherwise differences in colour don't mean differences in data.
Encoding negative values without a diverging scale
If your data goes negative, use a diverging colour scale (e.g. blue → white → red). A single-hue scale hides the sign.
// 09 — Real-world examples
Where you’ll see them
GitHub contribution graph
The most recognised calendar heatmap in the world — showing daily commit activity with green intensity levels.
Fitness and habit tracking
Apps like Strava, Apple Health, and Duolingo use calendar heatmaps to show streaks and daily consistency.
Editorial data journalism
News organisations use calendar heatmaps to show daily temperature records, air quality indices, and crime counts.
// 10 — Quick reference
Key facts
// 11 — Accessibility
Making it accessible
Calendar heatmaps rely entirely on colour, which is a challenge for colourblind users. Provide tooltips showing exact values on hover, and offer a data table fallback. Use ARIA labels to describe the overall pattern. Choose a colour ramp that is distinguishable under the most common forms of colour vision deficiency (e.g. blue or orange ramps instead of red-green).
// 12 — Variations
Common variations
Year-in-pixels
One row per month, one column per day-of-month. Popular in bullet journals and personal trackers.
Multi-year stack
Multiple years stacked vertically for year-over-year comparison.
Circular calendar
Days arranged in a spiral or radial layout — visually striking but harder to read.
Hour × day heatmap
Rows are hours of the day, columns are dates — useful for showing intraday patterns over weeks.
// 13 — FAQs
Frequently asked questions
What is a calendar heatmap?+
A calendar heatmap is a grid of small coloured cells, one per day, arranged in a calendar layout with weeks as columns and days of the week as rows. Colour intensity encodes the magnitude of a single numeric variable for each day.
When should you use a calendar heatmap?+
Use a calendar heatmap when showing daily activity or frequency across a full year. It also works well when you want to reveal day-of-week and seasonal patterns simultaneously, and when tracking personal metrics: exercise, commits, habits, mood.
When should you avoid a calendar heatmap?+
Avoid a calendar heatmap when you need to show precise values — colour intensity is hard to decode. It is also a poor fit when your data has sub-daily resolution (use a line chart instead), or when you have multiple variables per day — heatmaps encode only one.
What data do you need to make a calendar heatmap?+
Two columns: a date and a numeric value. One row per day. Missing days are rendered as empty cells. The date column must be parseable (ISO 8601 is ideal).
How is a calendar heatmap different from a heatmap?+
Both a calendar heatmap and a heatmap can look similar at first glance, but they answer different questions. Reach for a calendar heatmap when the comparisons and patterns it was designed to reveal match what you need to communicate, and choose a heatmap when its particular strengths better fit your data and audience.
What is another name for a calendar heatmap?+
Calendar Heatmap is also known as GitHub-style heatmap, contribution graph. The name varies between fields, but the visualisation technique is the same.
What size of dataset works best for a calendar heatmap?+
Calendar Heatmap works best for 1 year of daily data, one variable. Outside that range the chart either looks empty or becomes too cluttered to read clearly.
Are calendar heatmaps accessible to screen readers?+
Calendar heatmaps rely entirely on colour, which is a challenge for colourblind users. Provide tooltips showing exact values on hover, and offer a data table fallback. Use ARIA labels to describe the overall pattern. Choose a colour ramp that is distinguishable under the most common forms of colour vision deficiency (e.g. blue or orange ramps instead of red-green).