Heatmap Calendar
ProA grid of coloured cells arranged in a calendar layout (weeks as columns, days as rows), where colour intensity represents data magnitude. Rendered as SVG rectangles. Used for visualising activity frequency, contributions, or any daily metric over months. Includes a colour scale legend and month labels.
4 variants
Variants
| Variant | Description | When to use |
|---|---|---|
| Default | Full-year calendar heatmap with 5-level colour intensity scale. | Use for showing daily activity over a year — commit history, workout streaks, usage patterns. |
| With Tooltip |
Usage Guidelines
Use a sequential colour scale (light to dark) for intensity.
Use diverging colour scales unless the data has a meaningful midpoint.
Include a legend showing what each colour level represents.
Omit the colour legend — users cannot interpret intensity without it.
Add tooltips on hover showing the exact date and value.
Rely on colour alone — provide exact values via tooltips and hidden table.
Provide a data table alternative listing dates and values for screen reader users.
Use more than 5 colour intensity levels — subtle differences become indistinguishable.
Code
Design Tokens
Accessibility
- Use role="img" with aria-label and aria-describedby for a summary.
- Include a hidden data table with date and value columns.
- Tooltips should be keyboard-accessible for each cell.
- Colour intensity must be paired with value labels in tooltips.
- Month and weekday labels should be visible text, not relying on spatial position alone.