JavaScript ChartsStyle Segments

Version 14.2.0

Style Segments allow customising the style of a series for defined ranges along an axis, making it easier to highlight thresholds, distinguish data ranges, or separate actual and predicted values.

Segmentation Copy Link

main.ts

import {
  AgCartesianChartOptions,
  AgCharts,
  AreaSeriesModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  UnitTimeAxisModule,
} from "ag-charts-community";
import { DataType, data } from "./data";

ModuleRegistry.registerModules([
  AreaSeriesModule,
  LegendModule,
  NumberAxisModule,
  UnitTimeAxisModule,
]);

const options: AgCartesianChartOptions<DataType> = {
  title: { text: "Performance Variance" },
  data,
  series: [
    {
      type: "area",
      yKey: "variance",
      xKey: "date",
      interpolation: {
        type: "smooth",
      },
      strokeWidth: 2,
      fillOpacity: 0.3,
      fill: "green", //used for the series
      stroke: "green", //used for the series
      segmentation: {
        key: "y", //segment along the y axis
        segments: [
          {
            stop: 0, //domain min until 0
            fill: "red", //used for this segment
            stroke: "red", //used for this segment
          },
        ],
      },
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      paddingOuter: 0,
    },
    y: {
      type: "number",
      title: { text: "Variance ($)" },
    },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export interface DataType {
  date: Date;
  variance: number;
}

export const data: DataType[] = [
  { date: new Date(2024, 0, 25), variance: -1 },
  { date: new Date(2024, 1, 25), variance: -7 },
  { date: new Date(2024, 2, 25), variance: -3 },
  { date: new Date(2024, 3, 25), variance: -12 },
  { date: new Date(2024, 4, 25), variance: -16 },
  { date: new Date(2024, 5, 25), variance: -4 },
  { date: new Date(2024, 6, 25), variance: -9 },
  { date: new Date(2024, 7, 25), variance: -5 },
  { date: new Date(2024, 8, 25), variance: -2 },
  { date: new Date(2024, 9, 25), variance: 18 },
  { date: new Date(2024, 10, 25), variance: 4 },
  { date: new Date(2024, 11, 25), variance: 9 },
  { date: new Date(2025, 0, 25), variance: 2 },
  { date: new Date(2025, 1, 25), variance: 14 },
  { date: new Date(2025, 2, 25), variance: 5 },
  { date: new Date(2025, 3, 25), variance: 22 },
  { date: new Date(2025, 4, 25), variance: 11 },
  { date: new Date(2025, 5, 25), variance: 1 },
  { date: new Date(2025, 6, 25), variance: 17 },
  { date: new Date(2025, 7, 25), variance: -15 },
  { date: new Date(2025, 8, 25), variance: -8 },
  { date: new Date(2025, 9, 25), variance: 8 },
  { date: new Date(2025, 10, 25), variance: 6 },
  { date: new Date(2025, 11, 25), variance: 3 },
  { date: new Date(2025, 11, 25), variance: 13 },
];

The segmentation option takes a key to determine which axis to use, and a segments array for the styles.

{
    series: [
        {
            type: 'area',
            yKey: 'variance',
            xKey: 'date',
            strokeWidth: 2,
            fillOpacity: 0.3,
            fill: 'green', //used for the series
            stroke: 'green', //used for the series
            segmentation: {
                key: 'y', //segment along the y-axis
                segments: [
                    {
                        stop: 0, //domain minimum until 0
                        fill: 'red', //used for this segment
                        stroke: 'red', //used for this segment
                    },
                ],
            },
        },
    ],
}

In this configuration:

The series fill and stroke are red when values fall below 0 on the y-axis.
The series fill and stroke are green when values are above 0 on the y-axis.
Properties fillOpacity and strokeWidth not specified in the segment are inherited from the series.

Segmentation Key Copy Link

Set segmentation.key: 'x' to segment along the xKey axis, or segmentation.key: 'y' to segment along the yKey axis.

main.ts

import {
  AgCartesianChartOptions,
  AgCharts,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
  UnitTimeAxisModule,
} from "ag-charts-community";
import { DataType, data } from "./data";

ModuleRegistry.registerModules([
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
  UnitTimeAxisModule,
]);

const options: AgCartesianChartOptions<DataType> = {
  title: { text: "Performance Variance" },
  data,
  series: [
    {
      type: "line",
      xKey: "date",
      yKey: "value",
      xName: "Date",
      yName: "Value",
      interpolation: {
        type: "smooth",
      },
      segmentation: {
        key: "x",
        segments: [
          {
            start: new Date("2025-01-01"),
            lineDash: [5, 10],
          },
        ],
      },
    },
  ],
  axes: {
    x: { type: "unit-time" },
    y: { type: "number" },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export interface DataType {
  date: Date;
  value: number;
  status: "actual" | "forecast";
}

export const data: DataType[] = [
  // Actuals
  { date: new Date("2024-07-01"), value: 120, status: "actual" },
  { date: new Date("2024-08-01"), value: 118, status: "actual" },
  { date: new Date("2024-09-01"), value: 121, status: "actual" },
  { date: new Date("2024-10-01"), value: 125, status: "actual" },
  { date: new Date("2024-11-01"), value: 128, status: "actual" },
  { date: new Date("2024-12-01"), value: 130, status: "actual" },
  { date: new Date("2025-01-01"), value: 129, status: "actual" },
  { date: new Date("2025-02-01"), value: 131, status: "actual" },
  { date: new Date("2025-03-01"), value: 133, status: "actual" },
  // Forecasts
  { date: new Date("2025-04-01"), value: 135, status: "forecast" },
  { date: new Date("2025-05-01"), value: 137, status: "forecast" },
  { date: new Date("2025-06-01"), value: 140, status: "forecast" },
  { date: new Date("2025-07-01"), value: 142, status: "forecast" },
  { date: new Date("2025-08-01"), value: 145, status: "forecast" },
];

{
    series: [
        {
            type: 'line',
            xKey: 'date',
            yKey: 'value',
            segmentation: {
                key: 'x',
                segments: [
                    {
                        start: new Date('2025-01-01'),
                        lineDash: [5, 10],
                    },
                ],
            },
        },
    ],
}

In the example above:

The series uses a solid stroke for 2024 and a dashed stroke for 2025 to distinguish actual and forecast data.

Segments Copy Link

Each segment in the segments array is defined by bounds and provides style overrides:

start / stop
- The axis range for the segment style to start and stop at.
- Omit start to begin at the axis minimum or the stop of the previous segment.
- Omit stop to end at the axis maximum or the start of the next segment.
Style properties
- These are the same styling keys available on the series, such as stroke and fill.
- Unspecified properties fall back to the main series options or defaults.

API Reference Copy Link

Properties available on the AgSeriesShapeSegmentOptions interface.

start AxisValue: The axis value at which the styles should start. This is the start of the axis domain by default.
stop AxisValue: The axis value at which the styles should stop. This is the end of the axis domain by default.
stroke AgCssColorOrRef: The colour for the stroke.
strokeWidth PixelSize: The width of the stroke in pixels.
strokeOpacity Opacity: The opacity of the stroke colour.
lineDash PixelSize[]: An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize: The initial offset of the dashed line in pixels.
fill AgColorType: 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.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsStyle Segments

Segmentation Copy Link

Segmentation Key Copy Link

Segments Copy Link

API Reference Copy Link