Skip to content

Heatmap

Use Heatmap to show how much happened on each day over weeks or a year, like GitHub’s contribution graph: commits, messages, tasks done, sign-ins. It answers “when were we busy” at a glance; for exact numbers over time, use a Table, and for a list of individual events, a Timeline.

Heatmap draws one cell per day: a column per week and a row per weekday, darker for larger values. Month names sit on top, weekday names on the left and a “Less … More” legend at the bottom right. Hovering or focusing a day shows a Tooltip with its date and value, which is also the day’s accessible name; arrow keys move between days. Days are local calendar days: "2026-11-19" is that day wherever the page is opened. When the weeks are wider than their container they scroll sideways, opening at the latest week; the weekday names stay put.

Demos

Basic

data takes one { timestamp, value } per day, where timestamp is a Date, a millisecond timestamp or a YYYY-MM-DD string. The range runs from the earliest to the latest day in data; days without an item count as 0. unit names the value in the tooltip.

Recent year

startDate and endDate set the range. fillCalendarLeading fills the days before the start in its first week, as GitHub’s profile does.

Color theme

colorTheme mixes the levels from a theme role, so they follow light and dark mode.

Custom colors and levels

activeColors replaces the levels above empty, light to dark; their number sets how many levels there are. Take them from the theme aliases so they follow the theme. By default a value’s level is its share of the largest value; thresholds sets the lowest value of each level instead.

Size and gaps

size sets the cell and label size; xGap and yGap set the space between columns and rows.

Labels and first day of the week

Turn the weekday names, month names and legend on or off. firstDayOfWeek picks the weekday on the top row; 0 is Sunday.

Tooltip and clicks

renderTooltip draws the tooltip’s content for a day, and tooltip takes Tooltip props such as placement (or false). onCellClick is called on a click, or on Enter or Space on a focused day.

footer goes on the left of the footer. indicatorLeadingText and indicatorTrailingText replace “Less” and “More”; indicator replaces the whole legend.

Loading

loading shows pulsing placeholder cells: a year of them without data, or the shape of data when it is there.

Props

NameTypeDefaultDescriptionVersion
dataHeatmapDataItem[]undefinedOne { timestamp, value } per day. Values on the same day add up; value: null marks a day with no data.Unreleased
startDateDate | number | stringundefinedFirst day shown. Defaults to the earliest day in data.Unreleased
endDateDate | number | stringundefinedLast day shown. Defaults to the latest day in data; without data, the 52 weeks up to today are shown.Unreleased
fillCalendarLeadingbooleanfalseShows the days before the start in its first week as empty days instead of blanks.Unreleased
firstDayOfWeek0 | 1 | 2 | 3 | 4 | 5 | 60The weekday on the top row. 0 is Sunday, as in Date.getDay().Unreleased
colorThemeprimary | info | success | warning | error | accentprimaryTheme role the levels are mixed from.Unreleased
activeColorsstring[]undefinedColors of the levels above empty, light to dark. Overrides colorTheme.Unreleased
minimumColorstringundefinedColor of empty days.Unreleased
thresholdsnumber[]undefinedThe lowest value of each level above empty, ascending. Without it a value’s level is its share of the largest value, rounded up.Unreleased
sizesmall | medium | largemediumCell and label size.Unreleased
xGapnumber | stringundefinedSpace between columns, in px or any CSS length. Defaults to the size’s gap.Unreleased
yGapnumber | stringundefinedSpace between rows, in px or any CSS length. Defaults to the size’s gap.Unreleased
showWeekLabelsbooleantrueShows the weekday names on the left.Unreleased
showMonthLabelsbooleantrueShows the month names on top.Unreleased
showColorIndicatorbooleantrueShows the legend at the bottom right.Unreleased
loadingbooleanfalseShows placeholder cells instead of values.Unreleased
unitstringundefinedNamed after the value in the tooltip and the days’ accessible names.Unreleased
tooltipboolean | HeatmapTooltipPropstrueThe tooltip on hover and focus. false turns it off; an object is passed to the Tooltip.Unreleased
renderTooltip(cell: HeatmapCell) => ReactNodeundefinedContent of a day’s tooltip. Defaults to its date and value.Unreleased
footerReactNodeundefinedContent on the left of the footer.Unreleased
indicatorReactNodeundefinedReplaces the legend.Unreleased
indicatorLeadingTextReactNodeundefinedText before the legend’s colors. Defaults to the locale’s “Less”.Unreleased
indicatorTrailingTextReactNodeundefinedText after the legend’s colors. Defaults to the locale’s “More”.Unreleased
onCellClick(cell: HeatmapCell, event: MouseEvent | KeyboardEvent) => voidundefinedCalled when a day is clicked, or chosen with Enter or Space.Unreleased

aria-label and aria-labelledby name the grid (it defaults to the locale’s “Heatmap”); other props go to the root div. size, colorTheme and firstDayOfWeek can be set for every heatmap through ConfigProvider’s componentOptions.Heatmap.

A HeatmapCell is { date, key, value, level, row, column }: date is the day’s local midnight, key the day as YYYY-MM-DD, value its total (0 for a day without data, null for a day recorded as no data) and level its color level, 0 for empty.

Month and weekday names and the dates in tooltips come from Intl in the language of ConfigProvider’s locale; the legend’s words and the “No data” text are in the locale’s Heatmap strings.