Heatmap Grid
A contribution-style calendar heatmap with a roving cursor and a readout that follows it.
heatmap-grid.tsxheatmap-grid.css
Checking access…
Overview
Weeks run left to right, days top to bottom, five intensity levels. Cells pop in with a diagonal stagger.
Hover a cell or focus the grid and use arrow keys; the header reads out that day.
When to use
- Activity, streaks, bookings or usage over weeks.
When not to use
- Exact comparisons between days: use bars.
Installation
$
pnpm dlx shadcn@latest add https://sundaeui.dev/r/heatmap-grid.json$
npx shadcn@latest add https://sundaeui.dev/r/heatmap-grid.json$
yarn dlx shadcn@latest add https://sundaeui.dev/r/heatmap-grid.json$
bunx --bun shadcn@latest add https://sundaeui.dev/r/heatmap-grid.jsonWorks in any React project. Files are written to components/sundae/. Read the source in the stage’s Code view. Pro assets need a personal token. See authenticated installs.
- No dependencies beyond React 18 or later.
- Copy heatmap-grid.tsx and heatmap-grid.css into components/sundae/.
- The CSS file is imported by the component, so no extra configuration is needed.
- Import the component and use it as shown below.
Usage
import { HeatmapGrid } from '@/components/sundae/heatmap-grid'
<HeatmapGrid weeks={weeks} describe={(w, d, v) => `${v} commits · week ${w + 1}`} />Props
| Prop | Type | Default |
|---|---|---|
weeks*Columns of seven values. | number[][] | — |
describe*Text for a cell. | (week, day, value) => string | — |
scaleFive colours, empty to hottest. | string[] | green scale |
titleHeading. | string | 'Activity' |
fillSurface: dark or light. | 'dark' | 'light' | 'dark' |
Accessibility
- A single focusable grid with arrow-key navigation, so it is one tab stop instead of a hundred.
- Every cell has an aria-label; the readout is a polite live region.
- Reduced motion removes the pop-in.
Customization
- Every colour is a CSS custom property on the root class; override them in your own stylesheet.
- fill="light" switches the built-in light palette.
Keyboard
- Arrow keys
- Move between days
- Home / End
- First / last week
FAQ
- Is Heatmap Grid free?
- Heatmap Grid is part of Sundae Pro. The live preview is open to everyone; the source installs with a Pro account.
- How do I install Heatmap Grid?
- Run npx shadcn@latest add https://sundaeui.dev/r/heatmap-grid.json. The files are written to components/sundae/. It has no dependencies beyond React 18 or later.
- Does Heatmap Grid support keyboard and screen readers?
- A single focusable grid with arrow-key navigation, so it is one tab stop instead of a hundred. Every cell has an aria-label; the readout is a polite live region.
- Does Heatmap Grid respect reduced motion?
- Reduced motion removes the pop-in.
More like this
All data →Pulse KPI
Data · UnderstatedStacked Bars
Data · Refined- Pro
Activity Rings
Data · Expressive - Pro
Scrub Sparkline
Data · Refined - Pro
Uptime Ticks
Data · Understated - Pro
Scatter Plot
Data · Refined