Heatmap

import { HeatmapDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';

export default Layout(MDX_DATA.Heatmap);

Usage

Heatmap is used to display data in a table where each column represents a week. The only required prop is data – an object where keys are dates in YYYY-MM-DD format and values are numbers.

The startDate and endDate props are optional; they are used to define the heatmap range. If not set, the heatmap will display data for the last year.

Data format

Heatmap expects data in the following format:

export const data = {
  '2025-02-14': 2,
  '2025-02-11': 3,
  '2025-02-06': 4,
  '2025-02-05': 1,
  '2025-02-03': 2,
  '2025-02-01': 2,
  '2025-01-31': 4,
  '2025-01-30': 2,
  // ...
};

With tooltip

Set the withTooltip and getTooltipLabel props to display a tooltip when Heatmap cells are hovered. getTooltipLabel is called with date and value and must return a string to display in the tooltip.

Change colors

Heatmap colors can be changed with the colors prop. It should be an array of any valid CSS color values (hex, rgba, CSS variables, etc.). By default, Heatmap uses 4 colors to indicate heat level, but you can pass any number of colors.

Colors depending on color scheme

If you want to change colors depending on the color scheme, you should define those colors in .css file:

Note that in this case, you can only use 4 colors without passing the colors prop. If you need more colors, you should pass them manually to the component:

import { Heatmap } from '@mantine/charts';
import { data } from './data';
import classes from './Demo.module.css';

function Demo() {
  return (
    <Heatmap
      data={data}
      startDate="2024-02-16"
      endDate="2025-02-16"
      classNames={classes}
      colors={[
        'var(--heatmap-level-1)',
        'var(--heatmap-level-2)',
        'var(--heatmap-level-3)',
        'var(--heatmap-level-4)',
        'var(--heatmap-level-5)',
        'var(--heatmap-level-6)',
      ]}
    />
  );
}

Values domain

By default, Heatmap calculates domain based on data values, for example, for the following data, the domain will be [1, 4]:

const data = {
  '2025-02-14': 2,
  '2025-02-11': 3,
  '2025-02-06': 4,
  '2025-02-05': 1,
};

Based on the domain, Heatmap calculates colors for each rect: 1 – min heat level, 4 – max heat level. To specify the domain manually, use the domain prop. It is useful when your data does not cover the whole range of possible values. For example, the subset of data passed to the heatmap has values from 1 to 4, but the actual range is from 1 to 10. In this case, you can pass [1, 10] to the domain prop:

import { Heatmap } from '@mantine/charts';

const data = {
  '2025-02-14': 2,
  '2025-02-11': 3,
  '2025-02-06': 4,
  '2025-02-05': 1,
};

function Demo() {
  return <Heatmap data={data} domain={[1, 10]} />;
}

Weekdays and months labels

Set the withMonthLabels and withWeekdayLabels props to display chart labels:

Month labels position

Set monthLabelsPosition="bottom" to display month labels below the heatmap:

Change labels text

To change labels, use the weekdayLabels and monthLabels props. The weekdayLabels prop must be an array of 7 strings with weekday names starting from Sunday. The monthLabels prop must be an array of 12 strings with month names starting from January.

Rect size, gap and radius

Pass props to rect

Use getRectProps to pass props to each rect. For example, it can be used to add an onClick handler to each rect:

Hide outside dates

First day of week

The default first day of the week is Monday; you can change it with the firstDayOfWeek prop:

Legend

Set withLegend to display a color legend below the heatmap. Use legendLabels prop to customize the labels (default: ['Less', 'More']):

Split months

Use splitMonths to separate months visually with a spacer column and show only days that belong to the current month in each column. Month labels will be shifted by one column when splitMonths is enabled and months with fewer than 2 weeks are not labeled.