CalendarHeatmap
Calendar heatmap — a week-column grid of day cells colored by value (GitHub-style).
Category: chart · WCAG 2.1-AA · chart, calendar, heatmap, time, data-viz
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | CalendarHeatmapDatum[] | — | Days: { day: string | Date, value }. |
title | string | — | Title text for the component. |
description | string | — | Supporting description text. |
from | string | Date | — | Range start (defaults to min day). |
to | string | Date | — | Range end (defaults to max day). |
width | number | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
height | number | 160 | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. It is a **cap on the drawn grid, never a crop**: cell size is clamped so all seven weekday rows fit inside it. |
maxCellSize | number | — | Optional ceiling on a cell's edge, in px. Cells are already clamped to fit `height`; set this only to keep them small in a short, wide range (GitHub's calendar uses ~11). Omitted by default so the height budget alone decides. |
tooltip | boolean | — | Whether to show tooltips on hover. |
className | string | — | Additional CSS class names merged onto the root element. |
plain | boolean | false | When true, renders a minimal variant without chart chrome. |
visualMap | VisualMapOptions | — | Map day value → CVD-safe colour (continuous or piecewise) via a keyboard-operable legend that filters the visible range. |
Design tokens
--cascivo-chart-2
When to use
- Showing a daily value over weeks/months (activity, contributions)
- Spotting weekly/seasonal patterns at a glance
When not to use
- Precise daily values — use a LineChart
- Non-date categories — use Heatmap
Examples
Contribution calendar
import { CalendarHeatmap } from '@cascivo/charts'
<CalendarHeatmap
title="Activity"
data={[{ day: '2026-01-01', value: 3 }, { day: '2026-01-02', value: 7 }]}
/>Related components
- Heatmap — Use for arbitrary x/y category grids