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 Sunday through Saturday (or Monday through Sunday, depending on convention) — the house calendar puts Sunday at the top, so the weekend is the first and last row. The colour scale is sequential or diverging, depending on whether the variable has a meaningful midpoint.

The hero chart above is two years of daily rider counts from the Harbour Bridge cycleway counter, 731 cells in a sequential teal. Three patterns are visible before any cell is read. The pale top and bottom rows in each year are Sunday and Saturday: commuters are most of the traffic. The columns are darkest in late summer, lighten through autumn into the winter trough, and recover through spring. And the last week of December is a pale block in both years — the holiday lull. Randomise it and every day's count jitters, but the weekend stripes and the seasons remain, because they are structural rather than daily.

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.
Fourteen incidents in a year
Sparse data on a calendar. Three hundred and fifty-one empty cells and fourteen dark ones: the grid is doing no work except to make the reader hunt. A dated list, or a timeline with fourteen labelled marks, would say when each incident was and what it was.

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. The house ramp is four steps of teal, and four is enough: a reader can name light, medium, dark and darkest, and no more.

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 1,400–3,200 wastes the scale's lower half. The two figures below are the same year of cycleway counts; only the colour domain differs.

Scale anchored at zero
The domain runs from 0 to the maximum, but no day is below about 600. Weekdays all land in the top two steps, weekends in the middle two, and the whole lowest step goes unused. The seasons have almost vanished.
Scale anchored to the data
The same year with the domain set by the data's own extent. All four steps are in use, the autumn peak and the winter trough are back, and the rainy days stand out as pale cells in otherwise dark weeks.

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. Every calendar on this page carries them.

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. Where the tooling has no per-cell annotation, name the days in the subtitle and let the reader find them, as the hero's does for the holiday lull.

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. Where the tooling cannot draw one, the subtitle must say what the darkest and palest steps mean — darker is busier is the least a reader should be given.

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, as the hero is — work when the question is what changed between the years' rhythms. When the question is how much did each month grow, the year-over-year comparison is better served by overlaid lines, where the two years sit on one axis and the gap between them can be read.

The hero's two years as monthly totals
Riders per month, 2024 against 2025, on one axis. The calendar shows that 2025 was darker; the lines show by how much, and that the growth was concentrated in the cooler months. Different question, different form.

Anatomy

The composition of a calendar heatmap
An anatomical guide

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.

Reading list

  • Tufte, E. (1990). Envisioning Information. On dense small-multiple displays.
  • Few, S. (2009). Now You See It. On reading rhythm and exception in time-oriented data.
  • Wilke, C. (2019). Fundamentals of Data Visualization. On sequential colour scales and when to anchor them.