Heatmap calendar React chart component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Heatmap calendar is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import HeatmapCalendar from @/components/ui/heatmap-calendar.

import { HeatmapCalendar, type HeatmapDatum } from "@/components/ui/heatmap-calendar"

const data: HeatmapDatum[] = [
  { date: "2026-09-21", value: 12 },
  { date: "2026-09-22", value: 9 },
  { date: "2026-09-23", value: 15 },
  { date: "2026-09-24", value: 7 },
]

export function TeamActivity() {
  return (
    <HeatmapCalendar
      data={data}
      endDate="2026-09-24"
      locale="en-US"
      label="Northwind CRM team activity"
      labels={{
        total: (n) => `${n} activities in the last year`,
        cell: (value, date) => `${value} activities on ${date}`,
        empty: (date) => `No activity on ${date}`,
      }}
      onDateClick={(date) => console.log(date)}
    />
  )
}

Props

• data*
  HeatmapDatum[] = { date: string; value: number; label?: string }[]

  One entry per iso day ("2026-09-24"). Missing days count as 0, duplicate dates add up, days outside the window are ignored and negative values draw as 0. label names the value in the tooltip.

• endDatedefault ""
  string

  Iso day of the last column. Empty uses the newest date in data (never the clock, so the server and the browser agree).

• todaydefault ""
  string

  Iso day that gets the today ring. Empty uses the viewer's date, read after hydration.

• weeksdefault 53
  number

  Week columns in the window, ending with the week of endDate.

• weekStartsOndefault -1
  0 | 1 | 2 | 3 | 4 | 5 | 6 | -1

  First row of each column: 0 is Sunday, 1 Monday ... 6 Saturday; -1 follows the locale (Monday in en-GB, Sunday in en-US). Changes the row order and the weekday labels.

• levelsdefault 5
  number

  Color steps including the empty level. Ignored when thresholds are given.

• thresholds
  number[]

  Lower bound of each level above 0, ascending: [1, 5, 10, 20] gives five levels. Default: quantiles of the non-zero values, so any activity is at least level 1.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The hue of the scale. Level 0 is the foreground at 7% (see emptyColor), then the tone from 30% to 100% in equal steps. neutral is the foreground ink.

• colordefault ""
  string

  Any CSS color, a palette slot ("series-3") or a tone name. Replaces the tone.

• emptyColordefault ""
  string

  Fill of the days without activity (level 0 and its legend swatch): any CSS color or a palette slot. Empty uses the foreground at 7%, visible on white and on the dark surface.

• cellSizedefault "md"
  "sm" | "md" | "lg"

  10 / 12 / 16px cells with 2 / 3 / 4px gaps.

• radiusdefault "sm"
  "none" | "sm" | "md" | "full"

  Cell corners: 0 / 2 / 3px or circles. The legend swatches follow.

• overflowdefault "scroll"
  "scroll" | "fit"

  scroll: a horizontal rail that opens at the newest week, with edge fades and week snapping. fit: only the newest weeks that fit the width, nothing scrolls.

• showMonthLabelsdefault true
  boolean

  Short month names above the first column of each month, skipped when two would collide.

• showWeekdayLabelsdefault true
  boolean

  Monday, Wednesday and Friday in the locale's two-letter form, pinned while the rail scrolls.

• showLegenddefault true
  boolean

  The Less ... More scale under the grid.

• showTotaldefault true
  boolean

  The header sentence with the window's total (labels.total).

• showTooltipdefault true
  boolean

  The readout on hover, tap and keyboard focus. Cell labels and the table still carry every value when off.

• tooltipModedefault "auto"
  "auto" | "float" | "fixed"

  float rides beside the day, fixed pins above the grid (never under a finger); auto is fixed on touch screens.

• value
  string | null

  The selected day (iso) when you control it; it gets a 2px ring. Pair with onValueChange.

• defaultValuedefault "null"
  string | null

  The day selected at first (YYYY-MM-DD), uncontrolled; null selects none. The playground offers a few sample days.

• onValueChange
  (date: string | null) => void

  Called when a day is selected, or with null when the selection clears.

• onDateClick
  (date: string, datum: HeatmapDatum | null) => void

  A click, a second tap or Enter on a day; datum is null for days without data.

• valueFormatdefault "number"
  ChartValueFormat = "number" | "compact" | "currency" | "percent"

  How values print in the tooltip, the total, the cell labels and the table.

• currencydefault "USD"
  string

  ISO 4217 code for valueFormat currency ("$12,480").

• decimalsdefault 0
  number

  Fraction digits for values in the tooltip, the total and the table; auto by magnitude when unset (Auto in the playground).

• formatValue
  (value: number, context: { kind: "tooltip" | "label" | "table" | "total"; date?: string }) => string

  Replaces the built-in value formatting everywhere.

• localedefault ""
  string

  Locale for numbers, month and weekday names, dates and the first day of the week. Empty uses the UIProvider / LocaleProvider locale.

• animateddefault true
  boolean

  The column sweep on first view and the color crossfade on data changes. Reduced motion always shows the final state.

• loadingdefault false
  boolean

  A skeleton in the grid's box and in the total.

• emptyState
  ReactNode

  Replaces the grid when data is empty. Without it an empty heatmap shows the zero grid and labels.noData.

• labeldefault ""
  string

  Accessible name of the figure and the grid, caption of the table. Empty uses labels.table.

• descriptiondefault ""
  string

  A one-sentence takeaway for screen readers.

• surfacedefault ""
  string

  The color behind the heatmap, painted under the pinned weekday labels and the today ring. Empty uses the surface token; set it when the heatmap sits on another background.

• actions
  ReactNode

  Trailing content of the header row: a period switch, a link.

• labels
  Partial<HeatmapCalendarLabels>

  Strings: less, more, total(count, weeks), cell(value, date, datum), empty(date), noData, table, month, valueName, activeDays, loading. English by default.

• classNames
  Partial<Record<HeatmapCalendarSlot, string>>

  Classes for header, total, actions, scroller, grid, cell, month, weekday, legend, tooltip and table.

Parts

FAQ

Used in

More React chart and stat components