Charts - Heatmap

Heatmap charts visually represents data with color variations to highlight patterns and trends across two dimensions.

Guidelines

Heatmaps excel at revealing patterns, correlations, and anomalies in large datasets by using color intensity to represent values across a two-dimensional grid. They transform complex numerical data into intuitive visual patterns.

Pattern recognition: Perfect for identifying clusters, trends, and correlations in matrix-style data
Large dataset visualization: Handle thousands of data points effectively through color encoding
Comparative analysis: Compare values across two categorical dimensions simultaneously
Density and intensity mapping: Show concentration, frequency, or intensity across geographic or categorical spaces

When to use heatmaps:

You have data that can be organized in a matrix format (rows and columns)
You want to show relationships between two categorical variables
You need to visualize large amounts of data at once
Pattern detection is more important than precise individual values
You're analyzing correlations, time-based patterns, or geographic distributions

Data requirements:

Two categorical or ordinal dimensions (for x and y axes)
One continuous numerical dimension (for color intensity)
Data organized in a grid or matrix structure
Works well with normalized or standardized values
Benefits from consistent data density across the grid

Choose heatmaps when: you have matrix-style data, need to spot patterns in large datasets, want to show correlations between categorical variables, or when color coding can reveal insights not obvious in numerical tables.

Common applications: correlation matrices, time-series patterns (hour vs. day), geographic data, user behavior analysis, and performance metrics across categories.

Basics

Heatmap charts series must contain a data property containing an array of 3-tuples. The first two numbers in each tuple correspond to the x and y indexes of the cell, respectively. The third number is the value for the given cell.

<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
      ],
    },
  ]}
/>

You can specify x and y ticks with the xAxis and yAxis props.

<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

To customize the color mapping, use the zAxis configuration. You can either use the piecewise or continuous color mapping.

Highlight

You can choose to highlight the hovered element by setting highlightScope.highlight to 'item'. To fade the other item, set highlightScope.fade to 'global'.

<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 highlighted/faded effect is obtained by applying the CSS property filter: saturate(...) to cells. To modify this styling, use the heatmapClasses.highlighted and heatmapClasses.faded CSS classes to override the applied style.

In the following demo, we replace the highlight saturation by a border radius and reduce the saturation of the faded cells.

Common features

The heatmap shares several features with other charts. This section only explains the details that are specific to the heatmap. If you'd like to learn more about the shared features, you can visit their dedicated pages.

Axes

The Heatmap axes can be customized like any other chart axis. The available options are available in the axis customization page.

The Heatmap has an item tooltip that can be customized as described in the Tooltip documentation page.

The only difference of the Heatmap Tooltip is its default content. You can import the default tooltip, or only its content as follows:

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

Legend

The Heatmap comes with a legend which is by default the ContinuousColorLegend.

To display it set hideLegend to false. You can modify it with slots.legend and slotProps.legend.

<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

<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

API

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