Heatmap Chart

A GitHub-style calendar heatmap — one cell per day, colored by intensity — powered by Recharts

Basic Chart

Installation

npx shadcn@latest add @evilcharts/recharts-heatmap-chart

The heatmap is the GitHub contribution graph shape: a calendar year laid out as week columns, one square per day, with color intensity standing in for the value. <EvilHeatmapChart> is the container, and every part hangs off it as a compound member — <EvilHeatmapChart.Cell>, <EvilHeatmapChart.MonthLabel>, <EvilHeatmapChart.DayLabel>, <EvilHeatmapChart.Tooltip>, and <EvilHeatmapChart.Legend> — so a single import gives you the whole chart. The cells are intrinsic to the data, so <Cell> always renders and just configures the grid; the labels, tooltip, and legend follow presence semantics — omit one and it does not render.

import { EvilHeatmapChart, type ChartConfig, type HeatmapDatum } from "@/components/evilcharts/charts/recharts-heatmap-chart";

const data: HeatmapDatum[] = [
  { date: "2025-01-06", value: 3 },
  { date: "2025-01-07", value: 11 },
  { date: "2025-01-09", value: 1 },
];
 
const chartConfig = {
  contributions: {
    label: "Contributions",
    colors: {
      light: ["#9be9a8", "#40c463", "#30a14e", "#216e39"],
      dark: ["#0e4429", "#006d32", "#26a641", "#39d353"],
    },
  },
} satisfies ChartConfig;
 
<EvilHeatmapChart className="h-48" data={data} config={chartConfig}>
  <EvilHeatmapChart.Cell dataKey="contributions" />
  <EvilHeatmapChart.MonthLabel />
  <EvilHeatmapChart.DayLabel />
  <EvilHeatmapChart.Tooltip />
  <EvilHeatmapChart.Legend />
</EvilHeatmapChart>

Under the hood the grid is a Recharts ScatterChart: every day is a point on two numeric axes measured in cells — week columns along the top, weekday rows down the side — so the cells stay square at any container size and the axes double as the month and weekday labels. Each point is drawn as a rounded SVG rect carrying that day's ramp color.

config is the same contract as every EvilCharts chart — a key maps to a label and a per-theme colors array. See Chart Config for the full shape. Here the array does double duty: its length is the number of intensity levels, and each entry is that level's color. Colors resolve from CSS variables at runtime, so dark mode just works.

Note

With no range, the chart shows the trailing year ending on the latest date in data, so a feed of recent activity lays out the way GitHub does without any date math on your side.

Interactive Selection

Set isClickable on <Cell> to make days selectable. The selected day keeps full strength and wears a ring while the rest soften. Handle selection events with the root's onSelectionChange callback:

isClickable

<EvilHeatmapChart
  data={data}
  config={chartConfig}
  onSelectionChange={(selection) => {
    if (selection) {
      console.log("Selected:", selection.date, "Value:", selection.value);
    } else {
      console.log("Deselected");
    }
  }}
>
  <EvilHeatmapChart.Cell dataKey="contributions" isClickable />
  <EvilHeatmapChart.Tooltip />
</EvilHeatmapChart>

Loading State

isLoading='true'

Note

Pass isLoading to <EvilHeatmapChart> to show an animated gray skeleton of the grid while data loads. The intro sweep replays once the data lands.

Examples

Examples of the heatmap in different configurations. Customize the root range, weekStart, and scale, the <Cell> radius and gap, and more.

Calendar Year

range={2025} scale='linear'

Note

Pass a year to range for January through December. scale="linear" spreads the levels evenly between the smallest and largest value instead of by quantile.

Monday Start

weekStart='monday'

Note

weekStart="monday" puts Monday on the top row. <DayLabel labels> takes seven names, Sunday first — pass an empty string to leave a row unlabeled.

Rounded Cells

radius={6} gap={5}

Note

A shorter range — here one quarter — gives the cells room, so a larger radius and gap read as tiles rather than pixels.

Explicit Thresholds

thresholds={[3, 10]}

Note

thresholds pins the level boundaries. Zero stays empty; positive values below 3 are the first level, 3 up to 10 the second, 10 and up the third. Two cuts make three levels, so the config needs three colors — one per level.

API Reference

A root container plus a small set of composible parts. Render the root, then compose the parts you need as children.

EvilHeatmapChart

The root container. It owns the date window, the value → level mapping, shared selection state, and the loading skeleton. Everything visual is composed as children.

Prop	Type	Default	Description
data*	HeatmapDatum[]	–	One entry per day that has a value. `HeatmapDatum` is `{ date: string; value: number }`, where `date` is an ISO calendar date (`YYYY-MM-DD`). Days absent from the array render as empty cells; duplicate dates are summed.
config*	ChartConfig	–	Defines the series. The key named by `<Cell dataKey>` supplies a `label` and a per-theme `colors` array that becomes the intensity ramp — lightest first, strongest last. Same contract as every EvilCharts chart — see Chart Config.
children*	ReactNode	–	The composed parts — `<Cell />`, `<MonthLabel />`, `<DayLabel />`, `<Tooltip />`, and `<Legend />`.
className	string	–	Additional CSS classes for the chart container.
chartProps	ScatterChartProps	–	Escape hatch spread onto the underlying Recharts `ScatterChart`. `data`, `children`, and `margin` are owned by the root. See the ScatterChart documentation.
range	number \| string \| [string, string]	–	The calendar window. A year (`2025`) shows January through December, a month string (`"2025-03"`) shows that month, and an `[start, end]` pair of ISO dates shows that inclusive span. Omit it for the trailing year ending on the latest date in `data`.
weekStart	sunday\|monday	"sunday"	Which day sits on the top row of each week column.
cellSize	number	–	A fixed cell size in pixels. Omit it to fit square cells to the container's width (capped by its height) and re-fit on resize.
scale	quantile\|linear	"quantile"	How values map onto the ramp when no `thresholds` are given. `"quantile"` shares the non-zero days evenly across the levels, like GitHub, so a few huge days don't wash out the rest; `"linear"` divides the min→max span evenly.
thresholds	number[]	–	Explicit ascending level boundaries. Values below the first threshold are level one; each threshold a value reaches moves it up a level. `n` thresholds make `n + 1` levels, spread across however many colors the config provides.
defaultSelectedDate	string \| null	null	The ISO date selected on first render.
onSelectionChange	(selection: { date: string; value: number } \| null) => void	–	Called when a day is selected or deselected. Receives the day's `date` and `value`, or `null` on deselect. Fires on click while `<Cell />` has `isClickable` set.
isLoading	boolean	false	Shows the animated loading skeleton.
animation	boolean	true	Master switch for the intro sweep. Pass `false` to render the chart instantly.
animationType	none\|default	"default"	`"default"` pops the cells in column by column, left to right, on first render; `"none"` disables it. The OS reduce-motion preference falls back to `"none"` automatically.

Cell

Configures the day cells. Always renders — it names the config key to color the grid with and shapes each cell.

Prop	Type	Default	Description
dataKey*	string	–	The `config` key whose `colors` array forms the intensity ramp and whose `label` names the value in the tooltip.
radius	number	2	The corner radius of each cell in pixels. Set to 0 for square cells.
gap	number	3	The space between neighboring cells in pixels.
isClickable	boolean	false	Lets days be clicked to select/deselect them. The selected day keeps full strength and wears a ring while the rest soften.

MonthLabel

Shows month names above the grid, each over the column where the month begins. Its presence enables it; omit it and none show.

Prop	Type	Default	Description
labels	string[]	["Jan", …, "Dec"]	Twelve month names, January first.

DayLabel

Shows weekday names beside the grid. Its presence enables it; omit it and none show.

Prop	Type	Default	Description
labels	string[]	["", "Mon", "", "Wed", "", "Fri", ""]	Seven day names, Sunday first, regardless of `weekStart`. An empty string leaves that row unlabeled — the default labels every other row, like GitHub.

Tooltip

The hover tooltip. Its presence enables it; omit it and none shows. Hovering a day shows the formatted date as the title and the series label with that day's value beneath it. Hidden automatically while loading.

Prop	Type	Default	Description
variant	default\|frosted-glass	"default"	Controls the visual style of the tooltip surface.
roundness	sm\|md\|lg\|xl	"lg"	Controls the border-radius of the tooltip.
position	fixed\|variable	"variable"	Controls how the tooltip is anchored. `"variable"` follows the hovered cell (Recharts' default); `"fixed"` pins the tooltip to the top of the chart and only tracks the cell's X.
dateFormatter	(date: string) => string	–	Formats the hovered day's ISO date for the tooltip title. Defaults to `"Mar 3, 2026"` style English.
valueFormatter	(value: number) => string	(value) => value.toLocaleString()	Formats the hovered day's value.

Legend

The "Less → More" ramp rendered under the grid, one swatch per level plus the empty cell. Its presence enables it; omit it and none shows. Hidden while loading.

Prop	Type	Default	Description
align	left\|right	"right"	Which side of the chart the ramp sits on.
lessLabel	string	"Less"	Text before the ramp.
moreLabel	string	"More"	Text after the ramp.

Did you like the content?

Sankey ChartSankey charts for flow data with nodes and links, plus gradient colors

Heatmap BlocksReady-made calendar heatmap blocks, powered by Recharts

On This Page

Installation Usage Interactive Selection Loading State Examples Calendar Year Monday Start Rounded Cells Explicit Thresholds API Reference

Petabyte-scale schema-less ingest on a fully managed event store with 95%+ compression

Heatmap Chart

Documentation Index

Installation

Usage

Interactive Selection

Loading State

Examples

Calendar Year

Monday Start

Rounded Cells

Explicit Thresholds

API Reference