Heatmap

On this page

A heatmap shows a value for every day over several months, one square per day, darker for higher values. It's the quickest way to see weekly patterns and quiet periods. phApp.heatmap() comes with ph-app-charts.js.

A heatmap of daily deliveriesA heatmap of daily deliveries

Figure 1: Six months of daily deliveries

phApp.heatmap('#heatmap', {
  data: [
    { date: '2026-11-15', value: 412 },
    { date: '2026-11-16', value: 388 },
    /* one entry per day */
  ],
  label: 'Daily deliveries',
  format: phApp.format.number,
});
OptionDefaultWhat it does
data(required){ date: 'YYYY-MM-DD', value } for each day. Missing days count as zero.
startweeks before endThe first day shown
endthe latest day in dataThe last day shown
weeks26How many weeks to show when start isn't set
colorthe first chart colourThe colour for the highest values: a hex colour, or a space-separated rgb() such as rgb(var(--ph-green-3)), which follows the theme
cellSize12Square size in pixels
formattoLocaleString()Formats values in the day tooltips
label"Daily activity"The accessible name
emptyText"No activity yet"Shown when every value is zero

Weeks run in columns, with month names above and weekday names on the left. Hovering a day shows its date and value. The legend runs from "Less" to "More".

The heatmap is built from HTML elements, not a canvas, and redraws when the theme changes.

React

import { HeatmapCalendar } from 'ph-app-kit-react/charts';

<HeatmapCalendar data={days} format={format.number} />

Guidelines

  • Use it for daily values over at least a couple of months; for a few weeks, a bar chart is clearer.
  • Say what's counted and the period in the card title and description.
  • Give totals or averages in text nearby; the squares show patterns, not exact numbers.