Skip to main content

​
Overview

Heatmap charts display data in a matrix format where individual values are represented as colors. The intensity of the color represents the magnitude of the value, making it easy to identify patterns and outliers at a glance.

​
When to Use

Use heatmap charts when you need to:
  • Visualize matrix data with two categorical dimensions
  • Show correlations or relationships between variables
  • Display temporal patterns like activity over days and hours
  • Compare values across multiple categories simultaneously
  • Identify hot spots in geographic or spatial data
  • Analyze calendar data with time-based patterns

​
Basic Configuration

​
Series Type

Heatmap charts support multiple coordinate systems: 
import { HeatmapSeriesOption } from 'echarts/types/src/chart/heatmap/HeatmapSeries';

const option: HeatmapSeriesOption = {
  type: 'heatmap',
  coordinateSystem: 'cartesian2d'  // 'cartesian2d' | 'geo' | 'calendar' | 'matrix'
};

​
Data Format

Heatmap data is typically an array of coordinates with values: 
type HeatmapDataValue = OptionDataValue[];  // [x, y, value]

const data = [
  [0, 0, 5],   // x: 0, y: 0, value: 5
  [0, 1, 1],   // x: 0, y: 1, value: 1
  [1, 0, 4],   // x: 1, y: 0, value: 4
  [1, 1, 2]    // x: 1, y: 1, value: 2
];

​
Complete Example

​
Cartesian2D Heatmap

import * as echarts from 'echarts';

const hours = [
  '12am', '1am', '2am', '3am', '4am', '5am', '6am',
  '7am', '8am', '9am', '10am', '11am',
  '12pm', '1pm', '2pm', '3pm', '4pm', '5pm',
  '6pm', '7pm', '8pm', '9pm', '10pm', '11pm'
];
const days = [
  'Monday', 'Tuesday', 'Wednesday',
  'Thursday', 'Friday', 'Saturday', 'Sunday'
];

// Generate sample data: [day_index, hour_index, value]
const data = [];
for (let i = 0; i < 7; i++) {
  for (let j = 0; j < 24; j++) {
    data.push([i, j, Math.floor(Math.random() * 100)]);
  }
}

const option = {
  title: {
    text: 'Weekly Activity Heatmap'
  },
  tooltip: {
    position: 'top',
    formatter: function (params) {
      return `${days[params.value[0]]}<br/>${hours[params.value[1]]}: ${params.value[2]}`;
    }
  },
  grid: {
    height: '50%',
    top: '10%'
  },
  xAxis: {
    type: 'category',
    data: days,
    splitArea: {
      show: true
    }
  },
  yAxis: {
    type: 'category',
    data: hours,
    splitArea: {
      show: true
    }
  },
  visualMap: {
    min: 0,
    max: 100,
    calculable: true,
    orient: 'horizontal',
    left: 'center',
    bottom: '15%',
    inRange: {
      color: ['#313695', '#4575b4', '#74add1', '#abd9e9', 
              '#e0f3f8', '#ffffbf', '#fee090', '#fdae61', 
              '#f46d43', '#d73027', '#a50026']
    }
  },
  series: [
    {
      name: 'Activity',
      type: 'heatmap',
      data: data,
      label: {
        show: false
      },
      itemStyle: {
        borderRadius: 4
      },
      emphasis: {
        itemStyle: {
          shadowBlur: 10,
          shadowColor: 'rgba(0, 0, 0, 0.5)'
        }
      }
    }
  ]
};

const chart = echarts.init(document.getElementById('main'));
chart.setOption(option);

​
Coordinate Systems

Heatmap supports four coordinate systems (HeatmapSeries.ts:74):

​
1. Cartesian2D (Default)

Standard grid-based coordinate system with x and y axes. 
{
  coordinateSystem: 'cartesian2d',
  xAxisIndex: 0,
  yAxisIndex: 0
}
Default: coordinateSystem: 'cartesian2d' (HeatmapSeries.ts:109)

​
2. Geo Coordinate System

For geographic heatmaps with blur effect. 
{
  coordinateSystem: 'geo',
  geoIndex: 0,
  blurSize: 30,     // Blur size (default: 30)
  pointSize: 20,    // Point size (default: 20)
  minOpacity: 0,    // Minimum opacity (default: 0)
  maxOpacity: 1     // Maximum opacity (default: 1)
}

​
3. Calendar Coordinate System

Perfect for time-series data visualization. 
{
  coordinateSystem: 'calendar',
  calendarIndex: 0
}

​
4. Matrix Coordinate System

For specialized matrix visualizations. 
{
  coordinateSystem: 'matrix',
  matrixIndex: 0
}

​
Key Options (Cartesian2D)

​
itemStyle

Defines the visual style of heatmap cells. 
interface HeatmapStateOption {
  itemStyle?: ItemStyleOption & {
    borderRadius?: number | number[];  // Rounded corners
  };
  label?: SeriesLabelOption;
}

series: [{
  type: 'heatmap',
  itemStyle: {
    borderRadius: 4,        // Rounded corners
    borderWidth: 1,
    borderColor: '#fff'
  }
}]

​
emphasis

Defines the hover state appearance. 
emphasis: {
  itemStyle: {
    shadowBlur: 10,
    shadowColor: 'rgba(0, 0, 0, 0.5)',
    borderColor: '#333',
    borderWidth: 2
  }
}

​
Key Options (Geo Coordinate)

These options are specific to geographic heatmaps (HeatmapSeries.ts:77-80):

​
blurSize

Controls the blur radius of each data point. 
blurSize?: number;
Default: 30 (HeatmapSeries.ts:122)

​
pointSize

Controls the size of each data point before blurring. 
pointSize?: number;
Default: 20 (HeatmapSeries.ts:124)

​
minOpacity / maxOpacity

Controls the opacity range of the heatmap. 
minOpacity?: number;  // Default: 0
maxOpacity?: number;  // Default: 1

series: [{
  type: 'heatmap',
  coordinateSystem: 'geo',
  blurSize: 40,
  pointSize: 25,
  minOpacity: 0.2,
  maxOpacity: 0.9
}]

​
Data Item Options

​
HeatmapDataItemOption

Each data item can have individual styling: 
// From HeatmapSeries.ts:58-61
interface HeatmapDataItemOption {
  value: HeatmapDataValue;  // [x, y, value] or custom format
  itemStyle?: ItemStyleOption & {
    borderRadius?: number | number[];
  };
  label?: SeriesLabelOption;
}

series: [{
  type: 'heatmap',
  data: [
    {
      value: [0, 0, 100],
      itemStyle: {
        color: '#c23531',
        borderRadius: 8
      }
    },
    [0, 1, 50],  // Simple array format
    [1, 0, 75]
  ]
}]

​
Working with Visual Map

Heatmaps work best with the visualMap component to map values to colors: 
visualMap: {
  min: 0,
  max: 100,
  calculable: true,
  realtime: true,
  inRange: {
    color: [
      '#f7fbff', '#deebf7', '#c6dbef',
      '#9ecae1', '#6baed6', '#4292c6',
      '#2171b5', '#08519c', '#08306b'
    ]
  }
}

​
Dependencies

Heatmap charts depend on the coordinate system components (HeatmapSeries.ts:91): 
static readonly dependencies = ['grid', 'geo', 'calendar', 'matrix'];

​
Select State

Default select state styling (HeatmapSeries.ts:130-134): 
select: {
  itemStyle: {
    borderColor: '#5470c6'  // Primary color on selection
  }
}

​
Performance Considerations

  • For large datasets (>10,000 points), consider aggregating data
  • Use progressive rendering for better performance
  • Geo heatmaps with blur effects are more computationally expensive
  • Disable labels (label.show: false) for dense heatmaps
  • Scatter Chart - Alternative for showing individual data points
  • Tree Map - Hierarchical alternative to matrix heatmaps
  • Calendar Chart - Specialized for temporal data

Build docs developers (and LLMs) love

Get started for freeTalk to us