CalendarHeatmap
A GitHub-style grid with one column per week and one cell per day, shaded by intensity, for showing the density of a daily time series.
Component behavior
CalendarHeatmap displays a daily metric on a calendar grid. It shows patterns rather than exact values: weekly rhythms, streaks, and gaps are visible without reading individual numbers.
Use cases
- Daily activity across weeks or months.
- Weekly patterns, seasonality, and consecutive activity.
- Compact daily summaries for dashboards or profiles.
Props
Pass values as { date, value } pairs; same-day entries are summed. Dates are bucketed in UTC, so the grid renders the same on the server and the client regardless of timezone. The range defaults to the extent of your data, snapped out to whole weeks.
| Prop | Type | Default | Description |
|---|---|---|---|
values | CalendarHeatmapValue[] | — | Daily entries. `date` may be a Date or an ISO string (parsed as UTC). Values on the same day are summed. |
startDate | Date | string | — | Pin the grid start. Defaults to the earliest value, snapped to a whole week. |
endDate | Date | string | — | Pin the grid end. Defaults to the latest value. |
maxValue | number | — | Intensity ceiling for the color ramp. Defaults to the largest daily value. |
color | string | primary | Color the filled cells ramp toward across five levels. |
weekStartsOn | 0 | 1 | 0 | First day of the week: 0 for Sunday or 1 for Monday. |
cellSize | number | 12 | Size of each day cell in pixels. |
gap | number | 3 | Spacing between cells in pixels. |
renderTooltip | (date: Date, value: number) => string | — | Custom tooltip text for a cell. Default is `"<value> · <ISO date>"`. |
Examples
Daily activity
import { CalendarHeatmap } from "@solarius/onset";
import type { CalendarHeatmapValue } from "@solarius/onset";