Heat maps were added in Highcharts in Version 4. A heat map displays data in a graphical format using colors and color ranges. Each value is contained in a matrix and is assigned a mid-tone color among extreme colors based on its value. This creates a visual representation of values in the map.

The data points are given in the form of an array that contains three elements. The first two elements are zero-index-based position coordinates in the matrix, and the third element is the actual value of the data point.

In the following example, we will plot the monthly climate data for Toronto with the help of a heat map by utilizing its various configuration options:

$( '#chart_container' ).highcharts({
    chart: {
        type: 'heatmap'
    },
    title: {
        text: 'Monthy Temperature Statistics - Toronto'
    },
    subtitle: {
        text: 'Source: <a href="http://theweathernetwork.com" target="_blank">The Weather Network</a>',
        useHTML: true
    },
    xAxis: {
        categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
    },
    yAxis: {
        categories: ['Average high', 'Average low', 'Average'],
        title: null
    },
    series: [{
        name: 'Temperature',
        data: [[0, 0, -1.1], [1, 0, -0.2], [2, 0, 4.6], [3, 0, 11.3], [4, 0, 18.5], [5, 0, 23.5], [6, 0, 26.4], [7, 0, 25.3], [8, 0, 20.7], [9, 0, 13.8], [10, 0, 7.4], [11, 0, 1.8],
            [0, 1, -7.3], [1, 1, -6.3], [2, 1, -2], [3, 1, 3.8], [4, 1, 9.9], [5, 1, 14.8], [6, 1, 17.9], [7, 1, 17.3], [8, 1, 13.2], [9, 1, 7.3], [10, 1, 2.2], [11, 1, -3.7],
            [0, 2, -4.2], [1, 2, -3.2], [2, 2, 1.3], [3, 2, 7.6], [4, 2, 14.2], [5, 2, 19.2], [6, 2, 22.2], [7, 2, 21.3], [8, 2, 17], [9, 2, 10.6], [10, 2, 4.8], [11, 2, -0.9]]
    }]
});

Both the axes in the preceding code have categories to represent the month and temperature type. This will produce a fairly simple heat map with all the values represented by a single default color:

We will now bring in the color axis and format it to align its legend to the right of the chart:

colorAxis: {
    minColor: '#499eee',
    maxColor: '#f39a6f'
},
legend: {
      align: 'right',
      layout: 'vertical',
      symbolHeight: 235,
      y: -22
}

We have defined #499eee and #f39a6f as the minimum and maximum color values respectively in the colorAxis component. This will give the heat map its well-known appearance, as shown in the following screenshot:

As you hover over data points in the chart, a marker will indicate the value range and its color in the legend. This marker can also be customized via the colorAxis.marker property, as shown in the following code:

colorAxis: {
    minColor: '#499eee',
    maxColor: '#f39a6f',
    marker: {
        animation: {
            duration: 100
        },
        color: 'red',
        width: 1
    }
}

This code will set the animation duration for the marker's movement to 100 milliseconds and change its color to red. The width property determines the size of the marker.

Fine-tuning the appearance

The data points in the heat map don't transition through colors, nor do they show data labels. If you would like to make them and their values more prominent, we can achieve it by setting the border and enabling data labels on the series:

series: [{
    name: 'Temperature',
    borderWidth: 1,
    borderColor: 'rgba(255, 255, 255, 0.3)',
    dataLabels: {
        enabled: true,
        style: {
            color: '#fff',
            'font-family': 'arial, helvetica, sans-serif',
            'font-size': '12px'
        }
    },
    data: [...]
}]

This will produce the following result:

Formatting the tooltip

The default tooltip for the preceding heat map does not display data in the correct format:

The data we need in the tooltip is the axes' value and the value of the data point. We can fix it by utilizing the formatter() method that we used in Chapter 3, Line and Spline Charts.

tooltip: {
    useHTML: true,
    formatter: function() {
        return '<strong>' + this.series.yAxis.categories[this.point.y] + '</strong><br /><strong>' + this.series.xAxis.categories[this.point.x] + ':</strong> ' + this.point.value + '&deg;C';
    }
}

Since we needed to show the respective categories of both the axes upon hovering over a data point, we accessed the categories array on the axes by this.series.xAxis.categories and this.series.yAxis.categories. For the correct element (category name) to show, we determined the index by this.point.x and this.point.y for xAxis and yAxis respectively. We then formatted the markup with simple HTML and returned the modified value.

The preceding code will produce the following result: