Charts - Heatmap

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

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.

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 chose 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',

<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.

Charts - Heatmap

Basics

Color mapping

Highlight

Common features

Axes

Tooltip

Legend 🚧

Labels 🚧

Custom item

API