---
title: "Colour Scale"
enterprise: true
framework: angular
version: "14.1.0"
---

# Colour 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](https://www.ag-grid.com/charts/angular/heatmap-series/), [Treemap](https://www.ag-grid.com/charts/angular/treemap-series/), [Sunburst](https://www.ag-grid.com/charts/angular/sunburst-series/), and [Scatter](https://www.ag-grid.com/charts/angular/scatter-series/) series.

## Simple Colour Scale

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

#### Simple Colour Scale

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Simple Colour Scale](https://www.ag-grid.com/charts/angular/colour-scale/examples/simple-colour-scale)

```js
{
    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](#gradient-legend) is displayed, showing how colours map to values.

Colour Scales are supported on [Heatmap](https://www.ag-grid.com/charts/angular/heatmap-series/), [Treemap](https://www.ag-grid.com/charts/angular/treemap-series/) and [Sunburst](https://www.ag-grid.com/charts/angular/sunburst-series/), [Scatter](https://www.ag-grid.com/charts/angular/scatter-series/) and [Bubble](https://www.ag-grid.com/charts/angular/bubble-series/) as well as all [Map](https://www.ag-grid.com/charts/angular/maps/) series types.

## Domain

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

#### Domain

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Domain](https://www.ag-grid.com/charts/angular/colour-scale/examples/fixed-domain)

```js
{
    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](#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

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

#### Discrete Mode

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Discrete Mode](https://www.ag-grid.com/charts/angular/colour-scale/examples/discrete-mode)

```js
{
    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](#colour-stops) to control the bin boundaries and the colours used.
- Discrete mode can use the [Gradient Legend](#gradient-legend) if desired. See [Legends](#legends) for details.

## Custom Colours

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

#### Custom Colours

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Custom Colours](https://www.ag-grid.com/charts/angular/colour-scale/examples/colour-stops)

### Colours

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

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

### Colour Stops

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.

```js
{
    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

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

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

### Missing Data

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

#### Missing Data

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Missing Data](https://www.ag-grid.com/charts/angular/colour-scale/examples/missing-data)

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

## Legends

The standard category [Legend](https://www.ag-grid.com/charts/angular/legend/) can be used with [Discrete Colour Scales](#discrete-mode), and the [Gradient Legend](#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.

#### Legend Type

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Legend Type](https://www.ag-grid.com/charts/angular/colour-scale/examples/legend-choice)

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

### Gradient Legend

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

#### Gradient Legend

```ts
// Angular entry point file
import '@angular/compiler';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent);
```

[Live example: Gradient Legend](https://www.ag-grid.com/charts/angular/colour-scale/examples/gradient-legend)

```js
{
    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](#reference-AgGradientLegendOptions) for all options.

## API Reference

#### Colour Scale

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| fills | AgColorScaleColorStop[] |  | Configuration for two or more colours, and the values they are rendered at. |
| fills.color (required) | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | Colour at this position. |
| fills.stop | number \| bigint |  | Position of this colour in the data domain. In continuous mode, the colour appears exactly at this value. In discrete mode, this is the first value of the next bin. |
| fills.name | string |  | Display name for this bin, used in legend and tooltip labels. |
| domain | [AgNumericValue, AgNumericValue] |  | Fixed domain for the colour scale. If unset, the domain is derived from the data extent. |
| mode | 'continuous' \| 'discrete' | continuous | Whether the fills should be rendered as a continuous gradient or discrete bins. |
| missingDataFill | CssColor |  | Fill colour for datums with no `colorKey` value. If unset, each series preserves its default behaviour for missing data. |

#### Gradient Legend

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| enabled | boolean |  | Whether to show the gradient legend. By default, the chart displays a gradient legend for series using a `colorKey`. |
| position | AgChartLegendPlacement \| AgChartLegendPositionOptions | 'bottom' | Position of the gradient legend. A placement keyword, or an object for fine-grained positioning. |
| gradient | AgGradientLegendBarOptions |  | Gradient bar configuration. |
| gradient.preferredLength | PixelSize |  | Preferred length of the gradient bar (may expand to fit labels or shrink to fit inside a chart). |
| gradient.thickness | PixelSize |  | The thickness of the gradient bar (width for vertical or height for horizontal layout). |
| spacing | PixelSize | 20 | The spacing in pixels to use outside the legend.  __Note:__ This only applies when `floating: false`. |
| reverseOrder | boolean |  | Reverse the display order of legend items if `true`. |
| scale | AgGradientLegendScaleOptions |  | Options for the numbers that appear below or to the side of the gradient. |
| scale.label | AgGradientLegendLabelOptions |  | Options for the labels on the scale. |
| scale.label.fontStyle | FontStyle |  | The font style to use for the labels. |
| scale.label.fontWeight | FontWeight |  | The font weight to use for the labels. |
| scale.label.fontSize | FontSize |  | The font size in pixels to use for the labels. |
| scale.label.fontFamily | FontFamily \| GoogleFontFamily \| Array<FontFamily \| GoogleFontFamily> |  | The font family to use for the labels. A single family name, or an array of names used as fallbacks. |
| scale.label.color | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour to use for the labels. A colour string, or a theme-colour reference object. |
| scale.label.minSpacing | PixelSize |  | Minimum gap in pixels between the axis labels before being removed to avoid collisions. |
| scale.label.format | string |  | Format string used when rendering labels. |
| scale.label.formatter | Formatter |  | Function used to render scale labels. If `value` is a number, `fractionDigits` will also be provided, which indicates the number of fractional digits used in the step between intervals; for example, an interval step of `0.0005` would have `fractionDigits` set to `4`. |
| scale.padding | PixelSize |  | Distance between the gradient box and the labels. |
| scale.interval | AgAxisContinuousIntervalOptions |  | Options for intervals on the scale. |
| scale.interval.step | number |  | The axis interval. Expressed in the units of the axis. If the configured interval results in too many items given the chart size, it will be ignored. `bigint` steps are accepted but precision is limited to the Number range. |
| scale.interval.maxSpacing | PixelSize |  | Maximum gap in pixels between items. |
| scale.interval.values | any[] |  | Array of values in axis units for specified intervals along the axis. The values in this array must be compatible with the axis type. |
| scale.interval.minSpacing | PixelSize |  | Minimum gap in pixels between intervals. |
| border | BorderOptions |  | The border around the legend. |
| border.enabled | boolean |  | Whether the associated elements and properties should be used in the chart. |
| border.stroke | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor |  | The colour for the stroke. |
| border.strokeWidth | PixelSize |  | The width of the stroke in pixels. |
| border.strokeOpacity | Opacity |  | The opacity of the stroke colour. |
| cornerRadius | PixelSize |  | The corner radius of the legend. |
| padding | PixelSize \| PaddingOptions |  | The padding between the border and legend items. A number applies uniform padding; an object sets each side. |
| fill | CssColor \| AgColorRef \| AgColorRefMixOnto \| AgColorRefMixOntoColor \| AgGradientColor \| AgPatternColor \| AgImageFill |  | The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill. |
| fillOpacity | Opacity |  | The opacity of the fill colour. |