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

Simple Colour Scale Copy Link

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

{
    series: [
        {
            type: 'heatmap',
            xKey: 'segment',
            yKey: 'service',
            colorKey: 'score',
            colorName: 'Score',
        },
    ],
}

In this configuration:

• colorKey is set to 'score', which supplies numeric values for the Colour Scale.
• 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.
• A Gradient Legend is displayed, showing how colours map to values.

Colour Scales are supported on Heatmap, Treemap and Sunburst, Scatter and Bubble as well as all Map series types.

Domain Copy Link

By default, the Colour Scale domain is derived from the data. Use colorScale.domain to set a fixed domain.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'segment',
            yKey: 'service',
            colorKey: 'score',
            colorScale: {
                fills: [{ color: 'tomato' }, { color: 'gold' }, { color: 'seagreen' }],
                domain: [1, 10],
            },
        },
    ],
}

In this example:

• Use the buttons to toggle domain between [1, 10] or the default of approximately 4 to 8.
• Using Custom Colours, the lowest values are tomato, the middle values are gold, and the highest values are seagreen.
  • With the fixed domain, the lowest value is 1 which is not in the data, so no cells appear as tomato.
  • With the default domain, the lowest value in the domain is 4 and appears as tomato.
• Values outside a fixed domain are clamped. In this example of [1, 10], a value of 0 would receive the same colour as 1.

Discrete Mode Copy Link

Use colorScale.mode to switch between a continuous gradient and discrete colour bins.

{
    series: [
        {
            type: 'heatmap',
            xKey: 'segment',
            yKey: 'service',
            colorKey: 'score',
            colorScale: {
                mode: 'discrete',
                domain: [0, 10],
                fills: [{ color: 'tomato', stop: 7 }, { color: 'gold', stop: 9 }, { color: 'seagreen' }],
            },
        },
    ],
}

In this example:

• In discrete mode, each data value receives a solid colour rather than a blended gradient.
• The number of bins is determined by the number of colours in the Colour Scale.
• Use Colour Stops to control the bin boundaries and the colours used.
• Discrete mode can use the Gradient Legend if desired. See Legends for details.

Custom Colours Copy Link

Use colorScale.fills to provide custom colours. Each item in the array specifies a color and an optional stop and name.

Colours Copy Link

Without stop values, colours are spaced equally across the data domain.

{
    colorScale: {
        fills: [{ color: 'tomato' }, { color: 'gold' }, { color: 'seagreen' }],
    },
}

Colour Stops Copy Link

With stop values, each colour is positioned at an explicit point in the domain. The fills array must be sorted in ascending stop order. The first and last fills default to the data minimum and maximum if no stop is set.

{
    colorScale: {
        fills: [{ color: 'tomato', stop: 7 }, { color: 'gold', stop: 9 }, { color: 'seagreen' }],
    },
}

In continuous mode, colours blend smoothly between stops:

• 0 → 7 interpolates from tomato to gold.
• 7 → 9 interpolates from gold to seagreen.
• 9 → 10 is solid seagreen.

In discrete mode, each stop marks a bin boundary:

• 0–6 is solid tomato.
• 7–8 is solid gold.
• 9–10 is solid seagreen.

Named Stops Copy Link

With name values, descriptive labels are used in the legend and tooltips instead of numeric ranges.

{
    colorScale: {
        fills: [
            { color: 'tomato', name: 'Detractor', stop: 7 },
            { color: 'gold', name: 'Passive', stop: 9 },
            { color: 'seagreen', name: 'Promoter' },
        ],
    },
}

Missing Data Copy Link

Set colorScale.missingDataFill to set the colour for a datum that has no value for the colorKey.

{
    colorScale: {
        missingDataFill: '#e0e0e0',
    },
}

Legends Copy Link

The standard category Legend can be used with Discrete Colour Scales, and the Gradient Legend can be used with both discrete and continuous Colour Scales.

The default legend depends on the colorScale.mode, but can be overridden by explicitly enabling or disabling each legend.

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

Gradient Legend Copy Link

The Gradient Legend displays a colour bar alongside the chart to help match colours to values.

{
    gradientLegend: {
        position: 'right',
        gradient: {
            thickness: 50,
            preferredLength: 400,
        },
    },
}

In the above example:

• position places the legend at the 'bottom', 'top', 'left', or 'right' of the chart.
  • When the position is left or right, values are displayed in descending order. Use reverseOrder to change this.
• gradient.thickness controls the width of the gradient bar.
• gradient.preferredLength sets the initial length of the gradient bar. The actual length may be adjusted to fit the chart dimensions or domain.
• Customise label appearance with scale.label (font, colour) and scale.padding (distance between bar and labels).

See the API Reference for all options.

API Reference Copy Link