Trend · Intermediate

Calendar heatmap

Daily amounts on a weekly grid.

Use when: The rhythm of daily activity, such as commits or orders
Avoid when: The period is shorter than a month

Try it

Reduce motion

Calendar heatmap

Daily commits in 2025

Calendar heatmap data
Wed, January 1	4
Thu, January 2	4
Fri, January 3	5
Sat, January 4	1
Sun, January 5	0
Mon, January 6	1
Tue, January 7	1
Wed, January 8	1
Thu, January 9	3
Fri, January 10	3
Sat, January 11	0
Sun, January 12	0
Mon, January 13	2
Tue, January 14	11
Wed, January 15	4
Thu, January 16	1
Fri, January 17	2
Sat, January 18	1
Sun, January 19	0
Mon, January 20	2
Tue, January 21	4
Wed, January 22	3
Thu, January 23	1
Fri, January 24	2
Sat, January 25	0
Sun, January 26	2
Mon, January 27	4
Tue, January 28	3
Wed, January 29	1
Thu, January 30	3
Fri, January 31	0
Sat, February 1	10
Sun, February 2	1
Mon, February 3	3
Tue, February 4	3
Wed, February 5	3
Thu, February 6	2
Fri, February 7	10
Sat, February 8	1
Sun, February 9	3
Mon, February 10	2
Tue, February 11	5
Wed, February 12	7
Thu, February 13	4
Fri, February 14	4
Sat, February 15	2
Sun, February 16	0
Mon, February 17	2
Tue, February 18	2
Wed, February 19	2
Thu, February 20	3
Fri, February 21	5
Sat, February 22	1
Sun, February 23	2
Mon, February 24	3
Tue, February 25	5
Wed, February 26	4
Thu, February 27	4
Fri, February 28	3
Sat, March 1	1
and 305 more

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example calendar --variant <id>) and the MCP server know the same names.

Weeks from Monday

Daily commits in 2025

No gaps

Daily commits in 2025

Code

CalendarHeatmap.tsx

import { ChartCard, CalendarHeatmap } from "ztd-charts";

const data = [
  {"date":"2025-01-01","commits":4},
  {"date":"2025-01-02","commits":4},
  {"date":"2025-01-03","commits":5},
  {"date":"2025-01-04","commits":1},
  {"date":"2025-01-05","commits":0},
  {"date":"2025-01-06","commits":1},
  // … 359 more rows
];

export function Example() {
  return (
    <ChartCard number="28" title="Calendar heatmap" subtitle="Daily commits in 2025" takeaway="Weekends are quiet" level="intermediate" replay>
      <CalendarHeatmap
        data={data}
        date="date"
        value="commits"
      />
    </ChartCard>
  );
}

Props

<CalendarHeatmap> takes these props. Rows marked Common work the same on every chart.

31 props

Above 4,000 items it draws on a canvas. Axes and labels stay SVG.

Prop	Type	Default	Description
`data`RequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]	object[]	-	An array of objects. Pass CSV, REST or database rows as they are
`date`RequiredDate fieldstring \| (d, i) => date	string \| (d, i) => date	-	Date field
`value`RequiredValue fieldstring \| (d, i) => number	string \| (d, i) => number	-	Value field
`weekStart`First day of the week (0 Sunday, 1 Monday)numberDefault `0`	number	0	First day of the week (0 Sunday, 1 Monday)
`gap`Gap between cells (px)numberDefault `2.5`	number	2.5	Gap between cells (px)
`canvasThreshold`Day count that switches to canvasnumberDefault `4000`	number	4000	Day count that switches to canvas
`dayFirst`Reads dates such as "05/03/2024", where either part could be the month, day first (5 March). Without it, a clear date in the column decides (25/03/2024), otherwise month first. true also reads "05.03.24" as day.month.yearboolean	boolean	-	Reads dates such as "05/03/2024", where either part could be the month, day first (5 March). Without it, a clear date in the column decides (25/03/2024), otherwise month first. true also reads "05.03.24" as day.month.year
`colorReverse`Darkest color for the smallest value, for rankings where 1st should stand out. The default highlight moves to the smallest value toobooleanDefault `false`	boolean	false	Darkest color for the smallest value, for rankings where 1st should stand out. The default highlight moves to the smallest value too
`colorCenter`Value that gets the lightest color. Values above take the accent color and values below take gray, so gains and losses split there (for example 0)number	number	-	Value that gets the lightest color. Values above take the accent color and values below take gray, so gains and losses split there (for example 0)
`colorSteps`Color in this many steps instead of a smooth scale. The heatmap legend shows each stepnumber	number	-	Color in this many steps instead of a smooth scale. The heatmap legend shows each step
`height`CommonHeight in px. Without it, each chart picks a default that fits its widthnumber	number	-	Height in px. Without it, each chart picks a default that fits its width
`width`CommonFixed width in px. Without it, the chart fits its parentnumber	number	-	Fixed width in px. Without it, the chart fits its parent
`highlight`CommonItem to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"number \| string \| (number\|string)[] \| "max" …	number \| string \| (number\|string)[] \| "max" …	-	Item to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"
`format`CommonValue format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options"number" \| "percent" \| "compact" \| …	"number" \| "percent" \| "compact" \| …	-	Value format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options
`unit`CommonUnit appended to values. For example "%" or "ms"string	string	-	Unit appended to values. For example "%" or "ms"
`locale`CommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault `"en-US"`	string	"en-US"	Locale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider locale
`animate`CommonEntry and update animationbooleanDefault `true`	boolean	true	Entry and update animation
`duration`CommonAnimation length (ms)number	number	-	Animation length (ms)
`easing`CommonMotion curve"spring" \| "easeOut" \| "easeInOut" \| "linear"Default `"spring"`	"spring" \| "easeOut" \| "easeInOut" \| "linear"	"spring"	Motion curve
`stagger`CommonDelay between items as they enter (ms)number	number	-	Delay between items as they enter (ms)
`reducedMotion`Common"auto" follows the OS setting. true always turns motion offanyDefault `"auto"`	any	"auto"	"auto" follows the OS setting. true always turns motion off
`animateOnView`CommonPlay when the chart scrolls into viewbooleanDefault `true`	boolean	true	Play when the chart scrolls into view
`showLabels`CommonLabels drawn on the chart (values and names)booleanDefault `true`	boolean	true	Labels drawn on the chart (values and names)
`tooltip`CommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault `true`	tooltip	true	Show tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left out
`syncId`CommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside itstring	string	-	Charts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside it
`ariaLabel`CommonName for screen readersstring	string	-	Name for screen readers
`description`CommonDescription for screen readers. Built from the data when omittedstring	string	-	Description for screen readers. Built from the data when omitted
`onHover`CommonRuns when hover or keyboard focus moves to another item(e: ChartEvent \| null) => void	(e: ChartEvent \| null) => void	-	Runs when hover or keyboard focus moves to another item
`onClick`CommonRuns on click, Enter or Space(e: ChartEvent) => void	(e: ChartEvent) => void	-	Runs on click, Enter or Space
`replayKey`CommonReplays the entry animation when it changesstring \| number	string \| number	-	Replays the entry animation when it changes
`theme`CommonChanges theme tokens for this chart onlyPartial<ChartTheme>	Partial<ChartTheme>	-	Changes theme tokens for this chart only

Try it

Variants

Code

Props

Also in Trend