Skip to content
GetUrUI

Activity Heatmap

Pro
.md

GitHub-style year heatmap on a volt intensity scale, with month labels, tooltips and arrow-key navigation across days; cells ripple in column by column.

chartheatmapcalendarcontributionsactivitysvg

When to use it

Use it for

  • Showing one number per day across a calendar year, GitHub-contribution style: commits, deploys, workouts, support tickets, logins or any other daily count.
  • Letting people spot streaks, quiet weeks and busy days, then pick a day to see its details elsewhere on the page.

Example: a year of deploys

example.tsx
1"use client";
2
3import * as React from "react";
4import { HeatCalendar, type HeatDatum } from "@/components/charts/heat-calendar";
5
6// Daily date/value rows; duplicate dates are summed. Dates must be YYYY-MM-DD; missing days are drawn as 0.
7const deploys: HeatDatum[] = [
8  { date: "2026-01-05", value: 2 },
9  { date: "2026-01-06", value: 5 },
10  { date: "2026-01-06", value: 1 },
11  { date: "2026-02-17", value: 9 },
12  { date: "2026-03-04", value: 7 },
13  { date: "2026-03-05", value: 3 },
14  { date: "2026-04-21", value: 14 },
15  { date: "2026-06-30", value: 4 },
16];
17
18// 1–2 deploys is level 1, 3–5 level 2, 6–10 level 3, 11 or more level 4.
19// Declared outside the component so the reference stays the same between renders.
20const THRESHOLDS: [number, number, number] = [2, 5, 10];
21
22export function DeployActivity() {
23  const [selected, setSelected] = React.useState<HeatDatum | null>(null);
24  return (
25    <div className="grid gap-2">
26      <HeatCalendar
27        data={deploys}
28        year={2026}
29        weekStart={1}
30        thresholds={THRESHOLDS}
31        unit="deploys"
32        onSelect={(date, value) => setSelected({ date, value })}
33      />
34      <p aria-live="polite" className="text-sm text-ink-muted">
35        {selected ? (
36          <>
37            {selected.value} deploys on {selected.date}
38          </>
39        ) : (
40          "Select a day to see its deploys."
41        )}
42      </p>
43    </div>
44  );
45}

What it needs from your app

  • Daily totals, or one row per event: data is an array of { date, value } and rows with the same date are summed, so { date, value: 1 } per event also works.
  • The component does not fetch data or convert timestamps into daily dates. It sums values from rows with the same exact YYYY-MM-DD date.
  • A client component: the file starts with "use client" and animates with Motion.

Choosing year, weekStart, thresholds, unit and onSelect

  • year: the grid always runs from January 1 to December 31 of one year. Without it, the year comes from the latest date in data, and an empty array draws 2026. Pass it whenever data can be empty or spans more than one year.
  • weekStart: 0 puts Sunday on the first row and labels the Mon, Wed and Fri rows; 1 puts Monday first and labels Tue, Thu and Sat.
  • thresholds: three ascending cut-offs that split values above 0 into four levels. A value equal to a cut-off stays in the lower level, so [2, 5, 10] gives 1–2, 3–5, 6–10 and 11 or more for whole numbers.
  • Without thresholds the cut-offs are 25%, 50% and 75% of the busiest day in the drawn year, so one unusual day pushes most others into the lightest level. Fixed thresholds also keep colours comparable between years or users.
  • Keep the thresholds array (and data) stable between renders, for example as a module constant or with useMemo: the grid is rebuilt whenever data, year, weekStart or thresholds change by reference.
  • unit: a plural noun used as written in the caption ("45 deploys in 2026"), the tooltip and each day's label. It is not made singular, so a day with one event reads "1 deploys".
  • onSelect(date, value): runs on click, Enter or Space with the YYYY-MM-DD date and that day's summed value. It also runs for empty days and for days later in the year. The calendar doesn't mark the chosen day, so keep the selection in your own state.

Data format and edge cases

  • date must be exactly YYYY-MM-DD with zero padding. Dates are matched as strings, so "2026-3-4", "2026/03/04" or a full timestamp like "2026-03-04T09:00:00Z" match no day and are left out without a warning.
  • Rows outside the drawn year are ignored and don't count toward the total.
  • Days missing from data are drawn as 0, so you don't need to fill gaps.
  • Values of 0 or below use the empty colour and don't count as active days, but negative values are still subtracted from the total in the caption. Pass counts of 0 or more.
  • The grid works on calendar dates and doesn't apply time zones. Turn event times into dates in the time zone your users expect before passing them: toISOString().slice(0, 10) gives the UTC date, which can move evening events to the next day.
  • Leap years get their extra day automatically.

Limits

  • It is a calendar activity heatmap: days of one year on a seven-row week grid. It is not a geographic heatmap of places or regions, and not a website click-tracking heatmap; it doesn't record clicks, scrolling or visitors.
  • It is also not a general matrix heatmap with your own axes, such as hour by weekday. The rows are always days of the week.
  • One calendar year per chart, January to December. There is no rolling last-12-months view; render one chart per year to show several.
  • Five levels on one colour ramp built from the --volt and --surface-sunken theme tokens. There is no colour prop; change the tokens, or levelColor in the installed source.
  • Month and weekday labels are English and numbers use en-US formatting; edit the source to change them.
  • The grid needs at least 600px of width and scrolls sideways inside narrower containers.

Pairs with

  • Sparkline Stats: Show totals and the trend for the same activity above the calendar.

See also

  • Pro registry: Activity Heatmap is a Pro item; install it with your registry token.
  • Installation: Set up the shadcn CLI, the registry and the theme tokens the colours use.
  • Theming: Change --volt to recolour the intensity scale.

Installation

Pro installs use your private registry token. Add the @geturui-pro registry once — setup guide. The command works after you get Pro.

$npx shadcn@latest add @geturui-pro/heat-calendar

Usage

usage.tsx
1import { HeatCalendar } from "@/components/charts/heat-calendar";
2
3<HeatCalendar
4  year={2026}
5  unit="commits"
6  data={[{ date: "2026-03-04", value: 7 }, { date: "2026-03-05", value: 2 }]}
7  onSelect={(date, value) => console.log(date, value)}
8/>

Props

PropTypeDefaultDescription
data*{ date: string; value: number }[]—ISO dates (YYYY-MM-DD); duplicates are summed.
yearnumber—Year to draw; defaults to the latest year in data.
weekStart0 | 10Sunday or Monday rows first.
thresholds[number, number, number]—Cut-offs for the four intensity levels; defaults to quarters of the max.
unitstring"contributions"Noun used in labels and the tooltip.
onSelect(date: string, value: number) => void—Click or Enter on a day.

Accessibility

  • One day is in the tab order; arrows move by day and week, Page Up/Down by month, Home/End to the ends of the year.
  • Each day has a label like “7 commits on Wed, Mar 4”.
  • Intensity uses a single-hue ramp and every value is available in text.

Related