Dashboards / Visual representation / Calendar heatmap

‹ 3 of 22 ›

Calendar heatmap

Daily activity over a year, read for streaks and gaps.

Updated September 10, 2026

Problem

A year of daily numbers is 365 points. As a line it is a hairy band where weekends and weekdays average together. The viewer wants to see that Tuesdays are busy, that August was quiet, and that one week in March went strange.

Solution

One cell per day, laid out as a calendar. Weeks as columns, days of the week as rows, colour for magnitude. A year fits in a strip a few centimetres tall and the eye picks out both the weekly rhythm and the seasonal one without being told to look.

The layout is the encoding. Because every row is the same weekday, a weekend effect appears as two consistently pale rows across the whole chart, which no line chart shows without being asked. Because columns are consecutive weeks, a quiet fortnight is a pale vertical gap. Both readings come free from the arrangement.

GitHub’s contribution graph is what made the pattern universally legible, and it also shows the pattern’s main weakness. Its cells are bucketed into a handful of intensity levels rather than mapped continuously, so a day with 4 commits and a day with 40 can look similar. That is a deliberate trade: coarse buckets make the rhythm readable and make individual days approximate. It works for that use and fails for any question about magnitude.

The variant worth knowing is the punch card: hour of day against day of week, cells sized or coloured by volume. Same idea, different cycle, and usually a better answer for anything with a daily shape rather than a weekly one.

Use when

The data has a genuine calendar rhythm, the period is long enough that a line chart becomes dense, and the question is about pattern rather than value. Deploys, incidents, sales, activity, on-call load.

Don’t use when

Exact values matter, or the period is short. A month of data in this layout is four columns and a line chart says more. Also poor for anything without a weekly cycle, where the row structure encodes nothing and only adds work.

Trade-offs

Colour carries all the magnitude, so the scale choice determines what is visible and a poorly chosen ramp can flatten a real seasonal change into uniformity. Outliers dominate: one enormous day pushes everything else to the bottom of the scale unless the range is clamped. The grid is small, so it fails at wallboard distance and on phones. And the pattern is strongly associated with GitHub, which means viewers arrive expecting “activity” semantics and read a gap as someone not working rather than as a metric being low.

Checklist

Does this data actually have a weekly or seasonal cycle worth showing?
Is the colour scale continuous or bucketed, and does that suit the question?
Is the range clamped so one outlier does not flatten the rest?
Is the scale legend present, with real values on it?
Does a zero-value day look different from a day with no data?
Are weekends or non-working days distinguished where that matters?
Which day does the week start on, and does it match the audience’s convention?
Is there a hover giving the date and the exact value?
Does the grid stay legible at the size it renders at?
Would viewers import GitHub’s “activity” reading and misinterpret a pale cell?

Compare

GitHub’s contribution graph is the reference implementation and the reason the pattern needs no explaining, using coarse intensity buckets that make the rhythm legible while making individual days deliberately approximate. Grafana has no calendar-layout panel in core, so teams reach for community plugins or reshape data into the standard heatmap, losing the calendar semantics that make the layout worth having. Datadog applies the punch-card variant to incident and alert timing, which is the strongest operational use of the idea because on-call load genuinely has an hour-of-day shape. Observable and D3 are where most bespoke versions get built, which is why the pattern is common in one-off analyses and rare inside monitoring products.

Heatmap is the general form, with continuous axes rather than calendar ones. Cohort grid uses the same cell-grid reading against cohort age. Sequential and diverging scales decides whether the colour ramp reveals or flattens. Status history is the strip version when the value is a state rather than a magnitude. Time series is the alternative when exact values matter more than rhythm.

Wireframe — the pattern's anatomy, not any one product's version of it

Implementation

A heatmap whose x-axis is the calendar, so weekly rhythm and holidays become visible. The empty cell has to differ from the zero cell or a quiet week reads as missing data.

Tokens: --card--muted--muted-foreground--border--scale-seq-1--scale-seq-2--scale-seq-3--scale-seq-4--scale-seq-5

LightDarkGreyscaleCode

LessMoreNo data

CalendarHeatmap.tsxLays days out by date, buckets values against thresholds the caller names, and draws a missing day as an outline rather than as zero.

/**
 * The layout is the encoding. Every row is one weekday and every column is
 * one week, so a weekend effect and a quiet fortnight are both visible from
 * the arrangement alone. Colour is bucketed on purpose: a handful of steps
 * makes the rhythm readable and makes individual days approximate, and the
 * exact value lives in the hover.
 *
 * `null` is a day with no data. It is drawn as an outline, because a day that
 * was not measured is a different fact from a day whose value was zero.
 */
const CELL = 10, GAP = 2, STEP = CELL + GAP;
const DAY = 86_400_000;
const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
/** Full class names, because Tailwind only ships the ones it can see. */
const FILL = ["fill-muted", "fill-scale-seq-1", "fill-scale-seq-2", "fill-scale-seq-3", "fill-scale-seq-4", "fill-scale-seq-5"];

export function CalendarHeatmap({ start, values, thresholds, unit, weekStart = 0, onSelect }: {
  /** ISO date of values[0]. */
  start: string;
  /** One entry per consecutive day. `null` means no sample arrived. */
  values: (number | null)[];
  /** Lower bound of each coloured step, ascending: five of them for a five-step ramp.
   *  Required, so the legend can show real values rather than "less" and "more" alone. */
  thresholds: number[];
  unit: string;
  weekStart?: 0 | 1;
  onSelect?: (date: string, value: number | null) => void;
}) {
  const t0 = Date.parse(start);
  const row = (t: number) => (new Date(t).getUTCDay() - weekStart + 7) % 7;
  const gridStart = t0 - row(t0) * DAY;
  const days = values.map((value, i) => {
    const t = t0 + i * DAY;
    return { t, value, col: Math.floor((t - gridStart) / (7 * DAY)), row: row(t) };
  });
  const cols = days[days.length - 1].col + 1;
  const bucket = (v: number) => thresholds.filter((th) => v >= th).length;
  const iso = (t: number) => new Date(t).toISOString().slice(0, 10);
  const monthStarts = days.filter((d) => new Date(d.t).getUTCDate() === 1 || d === days[0]);
  const left = 30, top = 16;
  const width = left + cols * STEP, height = top + 7 * STEP;

  return (
    <div>
      <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} role="img" aria-label={`${unit} per day from ${start}`} className="block max-w-full">
        {monthStarts.map((d) => (
          <text key={d.t} x={left + d.col * STEP} y={10} className="fill-muted-foreground text-[10px]">{MONTHS[new Date(d.t).getUTCMonth()]}</text>
        ))}
        {[0, 2, 4, 6].map((r) => (
          <text key={r} x={left - 6} y={top + r * STEP + CELL - 1} textAnchor="end" className="fill-muted-foreground text-[10px]">{DAYS[(r + weekStart) % 7]}</text>
        ))}
        {days.map((d) => (
          <rect
            key={d.t}
            x={left + d.col * STEP}
            y={top + d.row * STEP}
            width={CELL}
            height={CELL}
            rx={1.5}
            className={d.value === null ? "fill-none stroke-border" : FILL[bucket(d.value)]}
            onClick={onSelect && (() => onSelect(iso(d.t), d.value))}
          >
            <title>{`${iso(d.t)}: ${d.value === null ? "no data" : `${d.value} ${unit}`}`}</title>
          </rect>
        ))}
      </svg>

      <div className="mt-3 flex items-center gap-1.5 text-[10px] text-muted-foreground" style={{ marginLeft: left }}>
        <span>Less</span>
        {FILL.map((cls, i) => (
          <svg key={cls} width={CELL} height={CELL} aria-hidden="true">
            <rect width={CELL} height={CELL} rx={1.5} className={cls}>
              <title>{i === 0 ? `0 ${unit}` : i === FILL.length - 1 ? `${thresholds[i - 1]}+ ${unit}` : `${thresholds[i - 1]}–${thresholds[i] - 1} ${unit}`}</title>
            </rect>
          </svg>
        ))}
        <span>More</span>
        <svg width={CELL} height={CELL} aria-hidden="true" className="ml-3"><rect x={0.5} y={0.5} width={CELL - 1} height={CELL - 1} rx={1.5} className="fill-none stroke-border" /></svg>
        <span>No data</span>
      </div>
    </div>
  );
}

deploys.tsThe year's counts, one row per week. The quiet fortnight and the pale weekend rows are in the data, not the drawing.

/**
 * Deploys per day for 2023, one row per week starting on Sunday, 1 January.
 * The two quiet columns in July are the fortnight the team was off. The
 * weekend rows are quiet all year, and nothing has to be labelled for the
 * reader to see either.
 */
export const START = "2023-01-01";

export const WEEKS: number[][] = [
  [ 0,  0,  2,  0,  0,  2,  0],
  [ 0,  1,  3,  1,  1,  3,  0],
  [ 0,  1,  1,  3,  3,  3,  0],
  [ 0,  2,  2,  1,  3,  1,  0],
  [ 0,  1,  3,  3,  8,  3,  0],
  [ 0,  4,  2,  4,  7,  2,  0],
  [ 0,  1,  3,  2,  5,  2,  0],
  [ 2,  1,  8,  7,  2,  7,  0],
  [ 0,  2,  5,  1,  6,  6,  0],
  [ 1, 12,  1,  3,  5,  4,  3],
  [ 0,  7,  8,  5,  2, 11,  2],
  [ 3, 10, 10,  2,  4, 10,  3],
  [ 3, 12, 11, 12,  5,  5,  3],
  [ 1,  6, 16,  8,  3,  6,  1],
  [ 3, 11,  5,  6, 27, 11,  1],
  [ 2,  4,  8, 10,  6,  6,  3],
  [ 3, 30,  5, 10, 23, 11,  3],
  [ 2,  8, 14,  6, 15, 11,  2],
  [ 3, 12,  5, 14, 15,  8,  1],
  [ 1,  5,  4, 18, 25, 28,  1],
  [ 2, 20, 18, 25, 13,  8,  3],
  [ 1, 26, 17, 14, 21, 20,  3],
  [ 1, 28, 21, 20, 13, 23,  2],
  [ 3, 22, 30, 17,  6, 25,  1],
  [ 2, 27,  6,  4, 29, 23,  2],
  [ 3, 14,  4, 29,  5, 17,  1],
  [ 1, 27, 27, 24, 16, 11,  3],
  [ 2, 18, 19, 10, 13,  6,  1],
  [ 0,  0,  0,  0,  0,  0,  0],
  [ 0,  0,  0,  0,  0,  0,  0],
  [ 1, 12,  4, 15, 20,  4,  1],
  [ 1, 23, 12, 15, 26, 24,  1],
  [ 1,  7,  7, 23,  9, 14,  3],
  [ 1,  4,  5, 10,  5, 13,  2],
  [ 3,  2,  8, 12,  4, 13,  2],
  [ 0,  7, 15,  7, 13, 15,  1],
  [ 3,  6,  8, 15,  8, 15,  2],
  [ 1,  7,  4,  7,  1,  8,  0],
  [ 3,  3,  1,  2,  4,  2,  1],
  [ 0,  5,  2,  7,  3,  3,  2],
  [ 0,  6,  2,  1,  2,  2,  1],
  [ 0,  4,  4,  5,  1,  2,  0],
  [ 0,  6,  3,  8,  3,  2,  0],
  [ 0,  1,  2,  3,  2,  1,  0],
  [ 0,  3,  3,  3,  2,  1,  0],
  [ 0,  3,  2,  2,  1,  1,  0],
  [ 0,  3,  1,  2,  2,  3,  0],
  [ 0,  0,  1,  3,  1,  2,  0],
  [ 0,  0,  0,  3,  2,  3,  0],
  [ 0,  0,  2,  0,  2,  1,  0],
  [ 0,  0,  3,  0,  0,  0,  0],
  [ 0,  0,  1,  0,  2,  1,  0],
];

demo.tsxHow it is called: a year of deploys with five real thresholds on the legend and one unsampled day at the end.

import { CalendarHeatmap } from "./CalendarHeatmap";
import { START, WEEKS } from "./deploys";

/**
 * A year of deploys. The data stops on 30 December, so the last day of the
 * year has no sample and draws as an outline rather than as a quiet day.
 */
export default function Demo() {
  return (
    <div className="w-fit rounded-lg border bg-card p-4">
      <CalendarHeatmap
        start={START}
        values={[...WEEKS.flat(), null]}
        thresholds={[1, 4, 9, 16, 31]}
        unit="deploys"
        onSelect={(date, value) => console.log(date, value)}
      />
    </div>
  );
}

What it renders. Identical markup in all three panes, with only the token values changing.

Copy-paste: this implementation as plain text

Examples

Captures whose hotspots reference this pattern, grouped by product and dated. The dashed boxes are this pattern; hover any box for the note.

GitHub

The contribution graph is the calendar heatmap every other product copied, and its five-step bucketing is the deliberate trade that made it legible.

Profile / contribution graph September 11, 2026 github.com, signed out (public profile) medium · light · desktop-web Toggle hotspots

The calendar heatmap everyone else copied, and a good demonstration of what it trades away. 3,703 contributions across 365 days is about ten a day, and the scale has five steps, so almost every cell here lands in the middle two and the year reads as one flat field of mid-green. A day with five commits and a day with twenty-five are the same colour. That is the deliberate choice—coarse buckets make the rhythm readable and make any individual day approximate—but on a profile this active there is no rhythm left to read either, because the bucketing has flattened the variation it was meant to reveal. The layout still earns its place: weeks as columns and weekdays as rows means a weekend effect would show as two pale rows across the full width, and here it doesn't, which tells you something true about this person's week. The panel beside it is worse off. It is a four-axis diagram of code review, issues, pull requests and commits, and with 100% commits it collapses to a single straight line.

Calendar heatmap Fifty-three columns of weeks, seven rows of weekdays, and only Mon, Wed and Fri labelled to save the space.
KPI tile The total sits above the grid, so the cells have a denominator. Most calendar heatmaps omit this.
Sequential and diverging scales Five discrete steps rather than a continuous ramp, which is why ten commits and thirty share a colour.
Time-range picker Sixteen years as a list. No arbitrary range, no relative window—the only unit on offer is a calendar year.

Show 1 more example Hide the rest

Tableau Public

Thousands of dashboards made by people who are not designers, published without a review step. The best available sample of what the pattern language looks like in the wild.

Machine-readable: this page as markdown