---
title: "Colour Scale"
enterprise: true
framework: react
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/react/heatmap-series/), [Treemap](https://www.ag-grid.com/charts/react/treemap-series/), [Sunburst](https://www.ag-grid.com/charts/react/sunburst-series/), and [Scatter](https://www.ag-grid.com/charts/react/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

```tsx
import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          domain: [0, 10],
        },
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Simple Colour Scale](https://www.ag-grid.com/charts/reactFunctionalTs/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/react/heatmap-series/), [Treemap](https://www.ag-grid.com/charts/react/treemap-series/) and [Sunburst](https://www.ag-grid.com/charts/react/sunburst-series/), [Scatter](https://www.ag-grid.com/charts/react/scatter-series/) and [Bubble](https://www.ag-grid.com/charts/react/bubble-series/) as well as all [Map](https://www.ag-grid.com/charts/react/maps/) series types.

## Domain

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

#### Domain

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgHeatmapSeriesOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "Average Rating",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          fills: [
            { color: "tomato" },
            { color: "gold" },
            { color: "seagreen" },
          ],
        },
      },
    ],
    gradientLegend: {
      gradient: { preferredLength: 200 },
      scale: { interval: { step: 1 } },
    },
  });

  const setDomain = (type: "auto" | "fixed") => {
    const nextOptions = clone(options);

    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    series.colorScale = {
      ...series.colorScale,
      domain: type === "fixed" ? [1, 10] : undefined,
    };

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          Domain:
          <button onClick={() => setDomain("fixed")}>Fixed [1, 10]</button>
          <button onClick={() => setDomain("auto")}>Auto</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Domain](https://www.ag-grid.com/charts/reactFunctionalTs/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

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgHeatmapSeriesOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          mode: "discrete",
          domain: [0, 10],
          fills: [
            { color: "tomato", stop: 7 },
            { color: "gold", stop: 9 },
            { color: "seagreen" },
          ],
        },
      },
    ],
    legend: {
      enabled: true,
    },
    gradientLegend: {
      enabled: false,
    },
  });

  const toggleMode = () => {
    const nextOptions = clone(options);

    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    const current = series.colorScale?.mode;
    const discrete = current !== "discrete";
    series.colorScale = {
      ...series.colorScale,
      mode: discrete ? "discrete" : "continuous",
    };
    nextOptions.legend = { enabled: discrete };
    nextOptions.gradientLegend = { enabled: !discrete };

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          <button onClick={toggleMode}>Toggle Mode</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Discrete Mode](https://www.ag-grid.com/charts/reactFunctionalTs/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

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgColorScaleColorStop,
  AgHeatmapSeriesOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

const equalFills: AgColorScaleColorStop[] = [
  { color: "tomato" },
  { color: "gold" },
  { color: "seagreen" },
];
const stopFills: AgColorScaleColorStop[] = [
  { color: "tomato", stop: 7 },
  { color: "gold", stop: 9 },
  { color: "seagreen" },
];
const namedFills: AgColorScaleColorStop[] = [
  { color: "tomato", name: "Detractor", stop: 7 },
  { color: "gold", name: "Passive", stop: 9 },
  { color: "seagreen", name: "Promoter" },
];
let currentMode: "continuous" | "discrete" = "continuous";
ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          fills: equalFills,
          domain: [0, 10],
        },
      },
    ],
    gradientLegend: {
      enabled: true,
      position: "right",
      gradient: {
        preferredLength: 200,
      },
    },
    legend: {
      enabled: false,
    },
  });

  const setMode = (mode: "continuous" | "discrete") => {
    const nextOptions = clone(options);

    currentMode = mode;
    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    const discrete = mode === "discrete";
    series.colorScale = { ...series.colorScale, mode };
    nextOptions.gradientLegend = {
      ...nextOptions.gradientLegend,
      enabled: !discrete,
    };
    nextOptions.legend = { ...nextOptions.legend, enabled: discrete };

    setOptions(nextOptions);
  };

  const setFills = (type: "equal" | "stops" | "named") => {
    const nextOptions = clone(options);

    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    const fills =
      type === "named" ? namedFills : type === "stops" ? stopFills : equalFills;
    series.colorScale = { ...series.colorScale, fills };

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          Mode:
          <button onClick={() => setMode("continuous")}>Continuous</button>
          <button onClick={() => setMode("discrete")}>Discrete</button>
          <span className="gap-left">Fills:</span>
          <button onClick={() => setFills("equal")}>Equal</button>
          <button onClick={() => setFills("stops")}>Stops</button>
          <button onClick={() => setFills("named")}>Named Stops</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Custom Colours](https://www.ag-grid.com/charts/reactFunctionalTs/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

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgHeatmapSeriesOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          domain: [0, 10],
          missingDataFill: "#e0e0e0",
        },
      },
    ],
  });

  const setMissingFill = (enabled: boolean) => {
    const nextOptions = clone(options);

    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    series.colorScale = {
      ...series.colorScale,
      missingDataFill: enabled ? "#e0e0e0" : undefined,
    };

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          Missing Data Fill:
          <button onClick={() => setMissingFill(true)}>On</button>
          <button onClick={() => setMissingFill(false)}>Off</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

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

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

## Legends

The standard category [Legend](https://www.ag-grid.com/charts/react/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

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  AgHeatmapSeriesOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  LegendModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          domain: [0, 10],
          fills: [
            { color: "tomato", stop: 7 },
            { color: "gold", stop: 9 },
            { color: "seagreen" },
          ],
        },
      },
    ],
    gradientLegend: {
      enabled: true,
      gradient: {
        preferredLength: 200,
      },
    },
    legend: {
      enabled: false,
    },
  });

  const setMode = (mode: "continuous" | "discrete") => {
    const nextOptions = clone(options);

    const series = nextOptions.series![0] as AgHeatmapSeriesOptions;
    series.colorScale = { ...series.colorScale, mode };

    setOptions(nextOptions);
  };

  const setGradientLegend = (enabled: boolean) => {
    const nextOptions = clone(options);

    nextOptions.gradientLegend = { ...nextOptions.gradientLegend, enabled };

    setOptions(nextOptions);
  };

  const setCategoryLegend = (enabled: boolean) => {
    const nextOptions = clone(options);

    nextOptions.legend = { ...nextOptions.legend, enabled };

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          Mode:
          <button onClick={() => setMode("continuous")}>Continuous</button>
          <button onClick={() => setMode("discrete")}>Discrete</button>
          <span className="gap-left">Gradient Legend:</span>
          <button onClick={() => setGradientLegend(true)}>On</button>
          <button onClick={() => setGradientLegend(false)}>Off</button>
          <span className="gap-left">Category Legend:</span>
          <button onClick={() => setCategoryLegend(true)}>On</button>
          <button onClick={() => setCategoryLegend(false)}>Off</button>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Legend Type](https://www.ag-grid.com/charts/reactFunctionalTs/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

```tsx
import React, { useState, Fragment } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgCartesianChartOptions,
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { getData } from "./data";
import clone from "clone";

ModuleRegistry.registerModules([
  CategoryAxisModule,
  GradientLegendModule,
  HeatmapSeriesModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgCartesianChartOptions>({
    data: getData(),
    title: {
      text: "Service Quality Ratings",
    },
    subtitle: {
      text: "NPS Score (0–10)",
    },
    series: [
      {
        type: "heatmap",
        xKey: "segment",
        xName: "Segment",
        yKey: "service",
        yName: "Service",
        colorKey: "score",
        colorName: "Score",
        colorScale: {
          domain: [0, 10],
          fills: [
            { color: "tomato", stop: 7 },
            { color: "gold", stop: 9 },
            { color: "seagreen" },
          ],
        },
      },
    ],
    gradientLegend: {
      enabled: true,
      position: "right",
      scale: {
        label: {
          fontStyle: "italic",
          color: "red",
        },
        padding: 10,
      },
    },
  });

  const setPosition = (position: "bottom" | "right" | "left" | "top") => {
    const nextOptions = clone(options);

    nextOptions.gradientLegend = { ...nextOptions.gradientLegend, position };

    setOptions(nextOptions);
  };

  const setThickness = (event: Event) => {
    const nextOptions = clone(options);

    const thickness = Number((event.target as HTMLInputElement).value);
    nextOptions.gradientLegend = {
      ...nextOptions.gradientLegend,
      gradient: { ...nextOptions.gradientLegend?.gradient, thickness },
    };
    document.getElementById("thicknessValue")!.innerHTML = String(thickness);

    setOptions(nextOptions);
  };

  const setLength = (event: Event) => {
    const nextOptions = clone(options);

    const preferredLength = Number((event.target as HTMLInputElement).value);
    nextOptions.gradientLegend = {
      ...nextOptions.gradientLegend,
      gradient: { ...nextOptions.gradientLegend?.gradient, preferredLength },
    };
    document.getElementById("lengthValue")!.innerHTML = String(preferredLength);

    setOptions(nextOptions);
  };

  const setPadding = (event: Event) => {
    const nextOptions = clone(options);

    const padding = Number((event.target as HTMLInputElement).value);
    nextOptions.gradientLegend = {
      ...nextOptions.gradientLegend,
      scale: { ...nextOptions.gradientLegend?.scale, padding },
    };
    document.getElementById("paddingValue")!.innerHTML = String(padding);

    setOptions(nextOptions);
  };

  return (
    <Fragment>
      <div className="example-controls">
        <div className="controls-row">
          Position:
          <button onClick={() => setPosition("bottom")}>Bottom</button>
          <button onClick={() => setPosition("right")}>Right</button>
          <button onClick={() => setPosition("left")}>Left</button>
          <button onClick={() => setPosition("top")}>Top</button>
        </div>
        <div className="controls-row">
          Thickness:{" "}
          <input
            type="range"
            min="5"
            max="60"
            defaultValue="16"
            step="1"
            onInput={(event) => setThickness(event)}
          />
          <span id="thicknessValue">16</span>{" "}
          <span className="gap-left">Length:</span>
          <input
            type="range"
            min="50"
            max="500"
            defaultValue="100"
            step="10"
            onInput={(event) => setLength(event)}
          />
          <span id="lengthValue">100</span>{" "}
          <span className="gap-left">Padding:</span>
          <input
            type="range"
            min="0"
            max="40"
            defaultValue="10"
            step="1"
            onInput={(event) => setPadding(event)}
          />
          <span id="paddingValue">10</span>
        </div>
      </div>
      <AgCharts options={options} />
    </Fragment>
  );
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);
```

[Live example: Gradient Legend](https://www.ag-grid.com/charts/reactFunctionalTs/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. |