Charts - Heatmap

Use heatmap charts to show intensity as a grid of colored cells across two dimensions.

Overview

A heatmap shows how a numeric value varies across two dimensions as a grid of colored cells. Each cell is the intersection of an x and y category or tick, and color encodes the value.

Use heatmaps to spot areas of higher or lower intensity, clusters, or anomalies.

The demo below shows bicycle counts in Paris by day and hour.

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

MUI X Expired package version

Data from Paris Data

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 indices, 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 how values map to color. You can use piecewise or continuous scales. See Styling—Value-based colors for details.

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 the effect with the heatmapClasses.highlighted and heatmapClasses.faded classes.

The demo below uses border radius on the highlighted cell and reduced saturation for faded cells.

MUI X Expired package version

Click events

Use onItemClick to handle cell clicks.

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

MUI X Expired package version

Click on the chart

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

Shared features

Heatmap charts use the same axis, tooltip, and legend patterns as other charts. This section notes heatmap-specific details. See the linked pages for full options.

Axes

You can configure heatmap axes like other chart axes. See Axis—Customization for details.

The default heatmap tooltip is item-based. You can customize it with slots. See Tooltip for details.

The heatmap package exports the default tooltip and its content if you want to reuse or extend them:

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

Legend

The heatmap includes a ContinuousColorLegend by default.

Set hideLegend to true to hide the legend. 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 cells

Use the cell slot to replace the default cell shape or add labels.

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
You cannot style cells 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.