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.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#Recent year
startDate and endDate set the range. fillCalendarLeading fills the days before the start in its first week, as GitHub’s profile does.
| Mon |
|---|
| Wed |
| Fri |
| Nov | Dec | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#Color theme
colorTheme mixes the levels from a theme role, so they follow light and dark mode.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#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.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#Size and gaps
size sets the cell and label size; xGap and yGap set the space between columns and rows.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#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.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#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.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#Footer
footer goes on the left of the footer. indicatorLeadingText and indicatorTrailingText replace “Less” and “More”; indicator replaces the whole legend.
| Mon |
|---|
| Wed |
| Fri |
| Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
#Loading
loading shows pulsing placeholder cells: a year of them without data, or the shape of data when it is there.
| Mon |
|---|
| Wed |
| Fri |
#Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
data | HeatmapDataItem[] | undefined | One { timestamp, value } per day. Values on the same day add up; value: null marks a day with no data. | Unreleased |
startDate | Date | number | string | undefined | First day shown. Defaults to the earliest day in data. | Unreleased |
endDate | Date | number | string | undefined | Last day shown. Defaults to the latest day in data; without data, the 52 weeks up to today are shown. | Unreleased |
fillCalendarLeading | boolean | false | Shows the days before the start in its first week as empty days instead of blanks. | Unreleased |
firstDayOfWeek | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 | The weekday on the top row. 0 is Sunday, as in Date.getDay(). | Unreleased |
colorTheme | primary | info | success | warning | error | accent | primary | Theme role the levels are mixed from. | Unreleased |
activeColors | string[] | undefined | Colors of the levels above empty, light to dark. Overrides colorTheme. | Unreleased |
minimumColor | string | undefined | Color of empty days. | Unreleased |
thresholds | number[] | undefined | The lowest value of each level above empty, ascending. Without it a value’s level is its share of the largest value, rounded up. | Unreleased |
size | small | medium | large | medium | Cell and label size. | Unreleased |
xGap | number | string | undefined | Space between columns, in px or any CSS length. Defaults to the size’s gap. | Unreleased |
yGap | number | string | undefined | Space between rows, in px or any CSS length. Defaults to the size’s gap. | Unreleased |
showWeekLabels | boolean | true | Shows the weekday names on the left. | Unreleased |
showMonthLabels | boolean | true | Shows the month names on top. | Unreleased |
showColorIndicator | boolean | true | Shows the legend at the bottom right. | Unreleased |
loading | boolean | false | Shows placeholder cells instead of values. | Unreleased |
unit | string | undefined | Named after the value in the tooltip and the days’ accessible names. | Unreleased |
tooltip | boolean | HeatmapTooltipProps | true | The tooltip on hover and focus. false turns it off; an object is passed to the Tooltip. | Unreleased |
renderTooltip | (cell: HeatmapCell) => ReactNode | undefined | Content of a day’s tooltip. Defaults to its date and value. | Unreleased |
footer | ReactNode | undefined | Content on the left of the footer. | Unreleased |
indicator | ReactNode | undefined | Replaces the legend. | Unreleased |
indicatorLeadingText | ReactNode | undefined | Text before the legend’s colors. Defaults to the locale’s “Less”. | Unreleased |
indicatorTrailingText | ReactNode | undefined | Text after the legend’s colors. Defaults to the locale’s “More”. | Unreleased |
onCellClick | (cell: HeatmapCell, event: MouseEvent | KeyboardEvent) => void | undefined | Called 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.