Charts - Heatmap

Show data as a grid of colored cells to reveal patterns across two dimensions.

Overview

A heatmap shows intensity across two dimensions (categorical or continuous) as a grid of colored cells. It highlights areas of high and low concentration, so you can spot trends, clusters, or anomalies. Each cell is the intersection of two variables, with color representing the value.

Bicycle count: Paris - Rivoli street (West-East)

MUI X Expired package version

Data from Paris Data

Basics

A heatmap series must include a data property with an array of 3-tuples. Each tuple is [xIndex, yIndex, value]: the first two numbers are the cell's x and y positions, and the third is the cell value.

<Heatmap
  series={[
    {
      data: [
        [0, 2, 2.7], // Cell (0, 2) receives the value 2.7
        [1, 2, 4.5], // Cell (1, 2) receives the value 4.5
      ],
    },
  ]}
/>

Use the xAxis and yAxis props to set x and y ticks.

MUI X Expired package version

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data }]}
  height={300}
/>

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data }]}
  height={300}
/>

Press Enter to start editing

Color mapping

Use the zAxis configuration to customize color mapping. You can use piecewise or continuous value-based colors.

MUI X Expired package version

<Heatmap
  height={400}
  xAxis={[{ data: xData }]}
  yAxis={[{ data: yData, width: 80 }]}
  series={[{ data }]}
  zAxis={[
    {
      min: 20,
      max: 300,
      colorMap: {
        type: 'continuous',
        color: interpolateBlues,
      },
    },
  ]}
/>

<Heatmap
  height={400}
  xAxis={[{ data: xData }]}
  yAxis={[{ data: yData, width: 80 }]}
  series={[{ data }]}
  zAxis={[
    {
      min: 20,
      max: 300,
      colorMap: {
        type: 'continuous',
        color: interpolateBlues,
      },
    },
  ]}
/>

Press Enter to start editing

Highlight

Set highlightScope.highlight to 'item' to highlight the hovered cell. Set highlightScope.fade to 'global' to fade the other cells.

MUI X Expired package version

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data, highlightScope: { highlight: 'item', fade: 'global' } }]}
  height={300}
/>

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data, highlightScope: { highlight: 'item', fade: 'global' } }]}
  height={300}
/>

Press Enter to start editing

By default the highlight and fade use the CSS filter: saturate(...) property. You can override it with the heatmapClasses.highlighted and heatmapClasses.faded classes.

The demo below uses border radius for the highlight and reduces saturation for faded cells.

MUI X Expired package version

Click event

Use onItemClick to react when a cell is clicked.

The handler receives the click event as the first argument and an item object as the second. The item has xIndex and yIndex (cell position on the x- and y-axes) and, when the cell has data, dataIndex (position in the series data array).

MUI X Expired package version

Click on the chart

// Data from cell click
// The data will appear here

Common features

The heatmap shares many features with other charts. This section covers heatmap-specific details. See the linked pages for shared features.

Axes

Heatmap axes are customized like other chart axes. See Axis customization for options.

The heatmap has an item tooltip that you can customize as described in the Tooltip documentation.

The heatmap tooltip differs only in its default content. Import the default tooltip or its content:

import { HeatmapTooltip, HeatmapTooltipContent } from '@mui/x-charts/Heatmap';

Legend

The heatmap includes a ContinuousColorLegend by default.

Set hideLegend to false to show it. Customize it with slots.legend and slotProps.legend.

MUI X Expired package version

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data }]}
  height={300}
  hideLegend={false}
  slotProps={{
    legend: {
      direction: 'vertical',
      position: { vertical: 'middle' },
      sx: { height: 200 },
    },
  }}
/>

<Heatmap
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data }]}
  height={300}
  hideLegend={false}
  slotProps={{
    legend: {
      direction: 'vertical',
      position: { vertical: 'middle' },
      sx: { height: 200 },
    },
  }}
/>

Press Enter to start editing

Custom item

MUI X Expired package version

<Heatmap
  slots={{ cell: CustomCell }}
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data, highlightScope: { highlight: 'item' } }]}
  height={300}
/>

<Heatmap
  slots={{ cell: CustomCell }}
  xAxis={[{ data: [1, 2, 3, 4] }]}
  yAxis={[{ data: ['A', 'B', 'C', 'D', 'E'] }]}
  series={[{ data, highlightScope: { highlight: 'item' } }]}
  height={300}
/>

Press Enter to start editing

WebGL renderer 🧪

Heatmaps can have many cells, which can slow down rendering. Set the renderer prop to 'webgl' for better performance with large datasets.

The WebGL renderer has some limitations:

The cell slot is not supported
Cells cannot be styled with CSS

The demo below shows roughly 8,800 cells rendered with WebGL.

Yellow Taxi Trip Count - 2024

0
14,619

MUI X Expired package version

Source: NYC.gov

<Typography variant="h6" sx={{ alignSelf: 'center', textAlign: 'center' }}>
  Yellow Taxi Trip Count - 2024
</Typography>
<HeatmapPremium renderer="webgl" {...settings} />
<Typography variant="caption">Source: NYC.gov</Typography>

<Typography variant="h6" sx={{ alignSelf: 'center', textAlign: 'center' }}>
  Yellow Taxi Trip Count - 2024
</Typography>
<HeatmapPremium renderer="webgl" {...settings} />
<Typography variant="caption">Source: NYC.gov</Typography>

Press Enter to start editing

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.