A Heatmap Series displays data in a matrix format, using colours to denote the magnitude of the values.
Simple Heatmap
To create a Heatmap Series, use the heatmap
series type.
series: [
{
type: 'heatmap',
xKey: 'month',
yKey: 'year',
colorKey: 'temperature',
},
],
In this configuration:
xKey
is set to 'month', which is the category for the X Axis.yKey
is set to 'year', which is the category for the Y Axis.colorKey
is set to 'temperature', which supplies numerical values for the Colour Scale.
Customisation
Colour Range
Series items colours can be customised via the colorRange
configuration array.
series: [
{
type: 'heatmap',
xKey: 'month',
yKey: 'year',
colorKey: 'temperature',
colorRange: ['#d7301f', '#fef0d9'],
},
],
Colour Range can also have more than 2 values.
series: [
{
type: 'heatmap',
xKey: 'month',
yKey: 'year',
colorKey: 'temperature',
colorRange: ['#43a2ca', '#a8ddb5', '#f0f9e8'],
},
],
Labels
If label.enabled
is set to true
, the labels will show the numeric value from colorKey
.
colorKey: 'temperature',
label: {
enabled: true,
},
A label formatter
can be used to customise the label text.
colorKey: 'temperature',
label: {
enabled: true,
formatter: ({ datum, colorKey }) => {
const value = datum[colorKey];
return `${value.toFixed(0)}°C`;
},
},
Gradient Legend
The Gradient Legend aids in matching the colour coding of the heatmap series to the underlying values, and is enabled by default.
series: [
{
type: 'heatmap',
xKey: 'month',
yKey: 'year',
colorKey: 'temperature',
},
],
gradientLegend: {
enabled: true,
},
Position
By default the Gradient Legend is placed at the bottom of the chart. Use the position
option to change this.
gradientLegend: {
position: 'right',
reverseOrder: true,
},
In the above example, reverseOrder
is used to change the direction of the Gradient Legend to display the values from top to bottom.
Size
gradientLegend: {
gradient: {
thickness: 50,
preferredLength: 400,
},
},
In the above configuration:
thickness
controls the thickness (or width) of the gradient bar.preferredLength
sets the initial length of the gradient bar. It is only preferred, as the Gradient Legend is constrained by the container edges.
Labels
It is possible to customise the font, colour and padding of the labels by using the scale
options.
gradientLegend: {
scale: {
label: {
fontSize: 20,
fontStyle: 'italic',
fontWeight: 'bold',
fontFamily: 'serif',
color: 'red',
},
padding: 20,
},
},
API Reference
Properties available on the AgHeatmapSeriesOptions
interface.
The colour range to interpolate the numeric colour domain (min and max colorKey
values) into. For example, if the colour domain is [-5, 5]
and colorRange
is ['red', 'green']
, a colorKey
value of -5
will be assigned the 'red' colour, 5
- 'green' colour and 0
a blend of 'red' and 'green'.
Primary identifier for the series. This is provided as seriesId
in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique id
value.
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
Configuration for marker and series highlighting when a series or legend item is hovered over.
The name of the node key containing the colour value. This value (along with colorRange
configs) will be used to determine the cell colour.
A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
A human-readable description of the colour values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
Function used to return formatting for individual heatmap cells, based on the given parameters. If the current cell is highlighted, the highlighted
property will be set to true
; make sure to check this if you want to differentiate between the highlighted and un-highlighted states.
Properties available on the AgGradientLegendOptions
interface.
Whether to show the gradient legend. By default, the chart displays a gradient legend for series using a colorKey
.