React ChartsColour Scale

A Colour Scale maps numeric data values to colours, adding a visual dimension to the chart. This is used by series types that support a colorKey, such as Heatmap, Treemap, Sunburst, and Map series.

Simple Colour Scale Copy Link

To use a Colour Scale, set colorKey on the series to a data property containing numeric values.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorName: 'Temperature',
        },
    ],
}

In this configuration:

• colorKey is set to 'temperature', which supplies numeric values for the Colour Scale. The data domain is automatically derived from the data — in this case, approximately 3 to 19.
• colorName sets the title that appears next to the colour value in tooltips.
• The default colour scheme is applied as a continuous gradient across the data range.

Custom Fills Copy Link

Use colorScale.fills to provide custom colours. Each item in the array specifies a color.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorScale: {
                fills: [{ color: 'navy' }, { color: 'lightyellow' }, { color: 'darkred' }],
            },
        },
    ],
}

With three colours and no stop values, the colours are spaced equally across the data domain. In this example the data ranges from 3 to 19, so:

• 3 is navy.
• 11 (the midpoint) is lightyellow.
• 19 is darkred.
• Values between these points are a smooth gradient blend — e.g. 7 is a blend of navy and lightyellow.

Colour Stops Copy Link

Use stop values to position colours at specific points in the data domain, rather than distributing them equally.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorScale: {
                fills: [
                    { color: 'darkblue' },
                    { color: 'lightblue', stop: 5 },
                    { color: 'lightyellow', stop: 10 },
                    { color: 'orange', stop: 15 },
                    { color: 'darkred' },
                ],
            },
        },
    ],
}

In this configuration:

• The first item (darkblue) has no stop, so it defaults to the data minimum (~3).
• lightblue starts at 5 — values from 3 to 5 are a gradient from darkblue to lightblue.
• lightyellow starts at 10 — values from 5 to 10 are a gradient from lightblue to lightyellow.
• orange starts at 15 — values from 10 to 15 are a gradient from lightyellow to orange.
• The last item (darkred) has no stop, so it defaults to the data maximum (~19) — values from 15 to 19 are a gradient from orange to darkred.
• The fills array must be sorted in ascending stop order.

Fixed Domain Copy Link

By default, the Colour Scale domain is derived from the data extent. Use colorScale.domain to set a fixed domain, which is useful for ensuring consistent colours across multiple charts or datasets with a known value range.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorScale: {
                fills: [{ color: 'darkblue' }, { color: 'lightyellow' }, { color: 'darkred' }],
                domain: [0, 25],
            },
        },
    ],
}

In this configuration:

• domain is set to [0, 25], overriding the auto-detected range of approximately 3 to 19.
• 0 is darkblue, 12.5 is lightyellow, and 25 is darkred.
• Although the data only contains values from 3 to 19, the full 0–25 range is used. This means winter months (around 3–5) appear as a dark blue rather than the very darkest blue, because the colour for 0 is reserved for the bottom of the fixed range.
• Values outside the domain are clamped — a value of -5 would receive the same colour as 0.

Discrete Mode Copy Link

Use colorScale.mode to switch between a continuous gradient and discrete colour bins. In discrete mode, each data value receives a solid colour rather than a blended gradient.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorScale: {
                mode: 'discrete',
                fills: [
                    { color: 'steelblue', stop: 5 },
                    { color: 'lightblue', stop: 10 },
                    { color: 'lightyellow', stop: 15 },
                    { color: 'coral' },
                ],
            },
        },
    ],
}

In this configuration:

• Each stop is the first value of the next bin. So steelblue covers values below 5, lightblue covers 5 to 9, lightyellow covers 10 to 14, and coral covers 15 and above.
• Unlike continuous mode, there is no gradient blending — a value of 7 is exactly the same lightblue as a value of 9.
• When using discrete mode, a category Legend is shown by default instead of the Gradient Legend, with one item per bin.

Named Stops Copy Link

Use the name property on fills to provide descriptive labels that appear in the legend and tooltips.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'month',
            yKey: 'year',
            colorKey: 'temperature',
            colorScale: {
                mode: 'discrete',
                fills: [
                    { color: 'steelblue', name: 'Cold', stop: 5 },
                    { color: 'lightblue', name: 'Cool', stop: 10 },
                    { color: 'lightyellow', name: 'Mild', stop: 15 },
                    { color: 'coral', name: 'Warm' },
                ],
            },
        },
    ],
}

In this configuration:

• The legend shows 'Cold', 'Cool', 'Mild', and 'Warm' instead of the default numeric range labels ('0 - 5', '5 - 10', etc.).
• Tooltips also display the name for the matching bin — e.g. hovering a cell with temperature 7 shows 'Cool'.
• In continuous mode, name values appear at their stop positions on the Gradient Legend.

Legend Type Copy Link

Both the Gradient Legend and the standard category Legend can be used with Colour Scales, in either continuous or discrete mode. The chart automatically selects a default based on the mode:

• Continuous mode — Gradient Legend is shown by default.
• Discrete mode — Standard Legend is shown by default, with one item per colour bin.

This default can be overridden by explicitly enabling or disabling each legend. Use the buttons below to see how each combination looks.

{
    gradientLegend: {
        enabled: true,
    },
    legend: {
        enabled: false,
    },
}

Set gradientLegend.enabled and legend.enabled to choose which legend to display. For example, to force a Gradient Legend in discrete mode, enable the Gradient Legend and disable the standard Legend.

Gradient Legend Copy Link

The Gradient Legend aids in matching the colour coding of the series to the underlying values. It is enabled by default for series using a colorKey in continuous mode.

{
    gradientLegend: {
        enabled: true,
    },
}

Position Copy Link

By default the Gradient Legend is placed at the bottom of the chart. Use the position option to change this.

{
    gradientLegend: {
        position: 'right',
    },
}

When the position is left or right, the Gradient Legend displays the values in descending order. Use reverseOrder to change this.

Size Copy Link

{
    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 Copy Link

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

Supported Series Copy Link

The following series types support Colour Scales via colorKey and colorScale:

• Heatmap — cell colour
• Treemap — tile colour
• Sunburst — sector colour
• Map Shapes — region fill
• Map Lines — line colour
• Map Markers — marker colour

API Reference Copy Link