Headless heatmaps for flexible React apps.

Eight cell shapes, interactive 3D in plain SVG, and complete control over every colour, size, and label.

Browse examples

$ npm install @thilakbhat/heatmap-ui

Examples

Heatmaps for real use cases

Copyable heatmaps with data and palettes included.

Developer activity

Contribution calendar

The classic streak graph. The few untracked days show as missing, not as zero commits.

CalendarHeatmap
known: false

Team rhythms

Commit punchcard

Weekdays against hours. Size and colour both carry intensity, so it reads in greyscale.

circle
encode="both"

Personal goals

Habit tracker

Progress toward each daily goal as rings that fill up. A rest day is a zero; a day away without the app is unknown.

ring
known: false

Status pages & SRE

Service uptime

Ninety days across six services as thin status pills. Status is a category, so each day is painted directly; days before a service was monitored show as unknown, not as up.

cellWidth
cellHeight
cellColor

Product analytics

Cohort retention

A ragged triangle: newer cohorts have no later weeks yet, so those slots are hidden.

isSlotHidden
cellContent

Issue triage

Label co-occurrence

A symmetric matrix with the diagonal removed, shaded by quantile so every band gets used.

scale="quantile"
square

UX research

Tap density

Hex-binned hotspots on a log scale, so a faint halo of taps doesn't vanish next to the peak.

hexagon
scale="log"

Year-in-review

Deploy skyline

Six months of deploys as a lit city at night. Drag to orbit, press + or − to zoom, and focus a building to read its value.

CalendarHeatmap3D
blockStyle="building"
theme="night"
animation="grow"

Retail & ops

Store footfall

Lunch and after-work rushes as cylinders, with bitmap-patterned faces on every block.

shape="circle"
material="pattern"

Engineering management

Sprint velocity bricks

Story points per squad as LEGO bricks. A sprint that hasn't closed shows an outline.

Heatmap3D
blockStyle="lego"

Want to tune one? Open the playground. Change any prop and it writes the code for you.

Explore all use cases

Features

Every detail is a prop

No wrappers, no forks, no stylesheet overrides. The defaults match what readers already know from GitHub, and everything else is yours to change.

rounded
square
circle
diamond
hexagon
plus
bar
ring

Eight cell shapes

Rounded, square, circle, diamond, hexagon, plus, bar and ring. One prop switches between them, and hexagons offset their rows into a proper honeycomb.

3D without WebGL

An isometric scene in plain SVG, in the same package. No canvas, no three.js. Blocks can be solid, LEGO bricks or lit buildings.

Gaps that read as gaps

A missing value is not a zero. Unknown slots fade out and are announced as “No data” to screen readers, so an outage doesn’t look like a quiet day.

linear

quantile

Shading that fits your data

Linear, quantile, log, explicit thresholds, or your own function. Quantile keeps every band in use when one outlier would otherwise wash the grid out.

.heatmap {
  --heatmap-tooltip-bg: #0a0a0a;
  --heatmap-tooltip-text: #fafafa;
  --heatmap-label: #a3a3a3;
  --heatmap-cell-content-color: #fff;
}

Headless styling

Colour is a prop, not a theme file. The stylesheet handles structure and exposes a few CSS variables, so the chart takes on your design system instead of fighting it.

Accessible by default

Cells are focusable only when they carry information. Tooltips open on focus as well as hover. Colour can be doubled with size, and hover scaling respects reduced motion.

Static SVG export

renderHeatmap3DSvg returns the same scene as a string, without React or a DOM. It works in emails, READMEs and OG images.

Zero dependencies

React is the only peer dependency. Ships as typed ES modules with source maps, under the MIT license.

Quick start

Up and running in a minute

Works with Next.js, Vite, Remix, or any React 18+ setup.

1
Install the package
React 18.2 or newer is the only peer.
$ npm install @thilakbhat/heatmap-ui
2
Import the stylesheet once
Structure only. Colours come from props.
app/layout.tsx
```
import "@thilakbhat/heatmap-ui/styles.css";
```

Render a heatmap

Pass values in. Every other prop has a sensible default.

components/activity.tsx

"use client";

import { CalendarHeatmap } from "@thilakbhat/heatmap-ui";

const days = [
  { date: "2026-09-10", value: 4 },
  { date: "2026-09-11", value: 9 },
  { date: "2026-09-12", value: 2 },
];

export function Activity() {
  return <CalendarHeatmap values={days} to="2026-09-12" weeks={20} showLegend />;
}

Open source, free forever

heatmap-ui is MIT licensed and built in the open. Star the repo to follow along, open an issue if something reads wrong, or send a pull request.

View on GitHub

FAQ

Questions about React heatmaps

Learn how to build calendar heatmaps, contribution graphs, punchcards, and interactive 3D SVG charts with heatmap-ui.

What is heatmap-ui?

heatmap-ui is a headless React heatmap library for turning activity, analytics, and operational data into flexible visualizations. It gives you the chart structure without forcing a particular theme or layout.

Can I build a GitHub-style contribution calendar in React?

Yes. Use CalendarHeatmap to create a GitHub-style contribution graph or calendar heatmap with date-based values, month labels, legends, custom cell shapes, and explicit handling for days with no data.

Does heatmap-ui support interactive 3D heatmaps without WebGL?

Yes. The 3D heatmap components render interactive scenes in plain SVG, so you can use calendar skylines and other 3D charts without WebGL, canvas, or three.js.

Which heatmap chart types and cell shapes are included?

The package includes calendar heatmaps, punchcards, cohort matrices, label co-occurrence grids, tap-density maps, and 3D skylines. Choose from rounded, square, circle, diamond, hexagon, plus, bar, and ring cells.

Can I customize heatmap colours, size, labels, and tooltips?

Every chart is controlled with props. Set your own colours, scale, cell size, gap, labels, legends, tooltips, thresholds, and cell content so the heatmap fits your product design system.

How does heatmap-ui handle missing or unknown values?

Missing values are kept distinct from zero. Unknown slots can fade out, receive their own opacity, and be announced as no data, which keeps gaps and outages readable in a calendar or analytics heatmap.

Is the React heatmap library accessible?

Yes. Informative cells can be focused and announced, tooltips work with keyboard focus as well as hover, and colour can be paired with size or labels so patterns do not depend on colour alone.

How do I install heatmap-ui?

Install the package with npm, pnpm, yarn, or bun, then import a heatmap component and the stylesheet. React 18.2 or newer is the only peer dependency.