This entry is part of the Chart Index, the reference library for the Chart Design Field Guide.
The calendar heatmap is the most familiar specialised chart in modern dashboards, thanks to GitHub's contribution graph. Each day is a small cell, arranged in a grid of weeks and weekdays, coloured by a quantitative variable. The form is brilliant for daily-granularity data over months or years: it shows weekly rhythm, weekday-of-week effects, and long-term trends all in a single, scannable panel.
The form's compactness is the entire point. A line chart of daily values over 365 days is a long, thin smear. A calendar heatmap of the same data is a compact rectangle where every day is a separate, addressable cell, and the visual patterns — the late-summer dip, the December lull, the weekend pattern — emerge from the layout itself.
What it is
A calendar heatmap maps days to a grid arranged by week (columns) and weekday (rows), with each cell coloured by a quantitative variable. The columns flow left-to-right across weeks; the rows are Monday through Sunday (or Sunday through Saturday, depending on convention). The colour scale is sequential or diverging, depending on whether the variable has a meaningful midpoint.
Fifty-two columns across, seven rows down, 365 cells. The colour reveals daily activity. Weekly rhythm (weekends quieter than weekdays), seasonal patterns (summer dip, end-of-year surge), and exceptional days (a single dark cell standing out) all read at a glance.
When to use it
Calendar heatmaps are the right choice when:
- The data is daily with at least a few months of coverage.
- The reader's question is "what's the rhythm? what's the trend? what days were exceptional?"
- You want to expose weekday and seasonal effects without explicit decomposition.
- The audience is familiar with the form — GitHub's contribution graph, Google's frequency views.
- The display is a single-glance overview rather than a precise reading.
When not to use it
- Sub-daily data. Hourly or minute-level data does not fit the day-cell encoding. Use a heatmap of hour × day or a time-series.
- Sparse data. A year of mostly-empty cells with a few dark dots reads better as a list or annotated timeline.
- Precise comparison. Colour is one of the least accurate perceptual channels. Direct reading requires tooltips or paired numbers.
- Categorical data. Calendar heatmaps assume a continuous (or count) variable. For categorical day-types, use a colour-coded calendar instead.
Design principles
Use a perceptually uniform sequential scale
The colour scale should go from light to dark in one direction, with uniform perceptual steps. Viridis, magma, or a hand-tuned LAB-based ramp work. Avoid rainbow scales — they introduce false categorical breaks.
Anchor the scale to the data range
The scale's minimum and maximum should match the data's minimum and maximum (or a meaningful clip — e.g., 5th to 95th percentile). A scale anchored to 0 when the actual range is 50–200 wastes the scale's lower half.
Label months along the top
Even if the columns are weeks, the reader thinks in months. Place month labels above the columns where each month begins. Without month labels, the chart is an abstract grid.
Highlight notable days
A few specific days often carry the story — a launch day, an outage, a holiday. Annotate them with a thin outline, a label, or a different stroke. Few's principle of minimising visual lookup applies to calendar cells too.
Show the legend with the scale visible
A small colour-scale legend showing the value-to-colour mapping anchors the reading. Include the minimum and maximum values; for sequential scales, optionally include a midpoint. The legend belongs near the chart, not buried in a footnote.
Keep cells small but distinguishable
Cells of 10–14 pixels work well. Smaller and the eye cannot distinguish colours; larger and the chart loses density. Maintain a consistent small gap between cells (1–2 pixels) so each cell reads as discrete.
Be careful with multi-year charts
Calendar heatmaps work best for a single year. Multi-year charts — stacked annuals — sometimes work, but the year-over-year comparison task is often better served by overlaid line charts. Plan the encoding for the question.
Anatomy
A calendar heatmap's anatomy is a 7-row × 52-column grid with month labels along the top and a colour-scale legend below or beside. The grid carries the data; the labels anchor it in time.
Related types
- Heatmap (matrix) — the general form. Calendar heatmaps are a specialisation with a fixed two-axis structure.
- Line chart (year-over-year) — the conventional alternative for daily data. More precise, less compact.
- Pie chart for weekly cycle — for showing weekday effect alone. Different question.
- Streamgraph or area — for showing daily values as a smoothed shape over time.
- Bar chart by day-of-week — for the weekday-effect question alone.
Reading list
- Tufte, E. (1990). Envisioning Information. On dense small-multiple displays.
- GitHub Engineering (2014). Inside the contribution graph. The form's modern reference implementation.
- Mike Bostock (2009). Calendar View D3 examples. The web-native implementation pattern.