Skip to content
InsightCharts

Search

Search guides and components

Calendar heatmap

Colours every day of one or more years by a value, laid out as a grid of weeks.

Use when
Daily data over months or years where weekly rhythm, seasonality, streaks and gaps matter: activity, sales, incidents, habits.
Avoid when
Reading the trend or exact values (use line chart); fewer than about three months of days (use bar chart); a non-daily grain such as hour by weekday (use heatmap).

Preview

Commits per day to the main repository, 2024

Number of commits each day

Illustrative data. Pale cells are days with no commits.

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

No molecule or template lists calendar heatmap in its composes. It still fits any slot that takes a component.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/calendar-heatmap

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { CalendarHeatmap } from "insightcharts";

Examples

Three years, with a gap in the record

Steps per day, 2022 to 2024

Daily step count. There is no data for April 2023.

Illustrative data

Sparse events, Sunday start

Incidents logged per day, 2025

Daily incident count, weeks starting on Sunday

Illustrative data

Forced vertical with a fixed height

Commits per day, 2024

Props

PropTypeDefaultDescription
daterequiredstringDate field: ISO strings, Dates or epoch milliseconds. One cell per calendar day.
valuerequiredstringNumeric field that colours each day. Rows sharing a day are summed.
orientation"auto" | "horizontal" | "vertical""auto"Weeks left to right, or top to bottom. auto goes vertical under 480px.
weekStart"monday" | "sunday""monday"First day of the week.
domain[number, number]Fix the ends of the colour scale. Default: 0 to the maximum.
heightnumber | stringCommon prop, but note the default: when omitted the height follows the cell size, which follows the width, so cells stay square.
Common chart props 29

Every chart built with defineChart accepts these on top of its own props.

PropTypeDescription
dataDataInputRows, CSV text, a URL, { url, path }, an async function, or an Arrow-style table. Omit inside <InsightData>.
transformTransform | Transform[]A pipeline of transforms applied before drawing.
titlestringThe title. One plain statement of what the data shows, with the number and the period ("Monthly churn fell from 4.2% to 2.1% in 2024"), or a plain label ("Monthly churn, 2024"). One clause, no figures of speech.
subtitlestringMeasure, unit, population, period.
sourcestringData source, shown as "Source: ...".
notestringMethod notes or caveats.
heightnumber | stringCSS height of the plot. Default 360.
aspectnumberWidth / height. Overrides height.
highlightstring | string[]The entity (or entities) the title is about. Every other series is drawn in grey.
annotationsAnnotation[]Reference lines, shaded bands and callouts, in data coordinates.
formatFormatSpecHow to print values: "compact", "percent", "currency:USD", "{value} kg", Intl options, or a function.
legendbooleanShow the legend. Default: shown when there are two or more series.
selectboolean | stringMake marks clickable to filter. Inside <InsightData> the selection filters every other chart. Pass a field name, or true to use the chart's category field.
onSelect(values: string[], field: string) => voidCalled with the selected values whenever the selection changes.
optionEChartsOption | ((option: EChartsOption, ctx: BuildContext) => EChartsOption)Deep-merged over the generated ECharts option, or a function that receives and returns it. Use it for ECharts settings no prop covers.
themeThemeInputA theme, or a partial set of tokens merged over the surrounding theme, for this chart only.
modeModeInput"auto" (default) follows the page, "system" follows the OS, or force "light" / "dark".
rendererRendererInput"auto" (default) uses SVG for light charts and canvas for heavy ones.
animatebooleanSet false to disable animation. Reduced-motion preferences are always respected.
lazybooleanMount the chart only when it scrolls near the viewport. Default true.
groupstringLink tooltips with other charts sharing this group id.
exportableboolean | ExportFormat[]Show an export menu: true or a list of formats from png, jpeg, svg, pdf, csv, json.
tablebooleanShow a collapsible "View data" table under the chart.
altstringAccessible description: the chart type and measures, then the main pattern and the notable values.
idstringStable id for this chart's selection in the shared store.
onEventsRecord<string, ChartEventHandler>ECharts event handlers, e.g. { click: (params, chart) => {} }. Prefix a name with zr: to bind to the canvas itself.
onReady(chart: EChartsInstance) => voidCalled with the ECharts instance once it is created.
classNamestringClass name for the outer <figure>.
styleCSSPropertiesInline style for the outer <figure>.