JavaScript ChartsCross Lines

Version 14.3.0

Cross Lines are lines or shaded areas in a chart that denote additional information or thresholds, making them useful for data analysis.

Adding Cross Lines Copy Link

To add a Cross Line at a specific data value on an axis, use the crossLines property in the axis options.

A Cross Line can either be a line or a range, and multiple Cross Lines can be added to a single axis.

main.ts

import {
  AgChartOptions,
  AgCharts,
  CategoryAxisModule,
  CrossLinesModule,
  LegendModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

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

const options: AgChartOptions = {
  data: getData(),
  series: [
    {
      type: "line",
      xKey: "month",
      yKey: "temp",
    },
  ],
  axes: {
    x: {
      type: "category",
      title: {
        text: "Month",
      },
      crossLines: [
        {
          type: "range",
          range: ["Jun", "Sep"],
        },
      ],
    },
    y: {
      type: "number",
      title: {
        text: "Temperature (°C)",
      },
      crossLines: [
        {
          type: "line",
          value: 11,
        },
      ],
    },
  },
};

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

const chart = AgCharts.create(options);

{
    axes: {
        y: {
            type: 'number',
            crossLines: [
                {
                    type: 'line',
                    value: 11,
                },
            ],
        },
        x: {
            type: 'category',
            crossLines: [
                {
                    type: 'range',
                    range: ['Jun', 'Sep'],
                },
            ],
        },
    },
}

In this configuration:

A line is displayed on the vertical axis at value 11.
A range is displayed on the horizontal axis between June and September.
The value or range values should be the same types as those displayed in the axis.

Customising Cross Lines Copy Link

main.ts

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

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

const options: AgChartOptions = {
  data: getData(),
  series: [
    {
      type: "line",
      xKey: "date",
      yKey: "petrol",
      yName: "Petrol",
    },
    {
      type: "line",
      xKey: "date",
      yKey: "diesel",
      yName: "Diesel",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      title: {
        text: "Date",
      },
      crossLines: [
        {
          type: "range",
          range: [new Date(2019, 4, 1), new Date(2019, 6, 1)],
          strokeWidth: 0,
          fill: "#7290C4",
          fillOpacity: 0.4,
          label: {
            text: "Price Peak",
            placement: "top",
            fontSize: 14,
            fill: "#7290C4",
            fillOpacity: 0.4,
            cornerRadius: 4,
            border: {
              stroke: "#7290C4",
            },
          },
        },
      ],
    },
    y: {
      type: "number",
      title: {
        text: "Price in pence",
      },
      crossLines: [
        {
          type: "line",
          value: 142.45,
          stroke: "#7290C4",
          lineDash: [6, 12],
          label: {
            text: "142.4",
            placement: "right",
            fontSize: 12,
            color: "#000000",
          },
        },
        {
          type: "line",
          value: 133.8,
          stroke: "#7290C4",
          lineDash: [6, 12],
          label: {
            text: "133.8",
            placement: "right",
            fontSize: 12,
            color: "#01c185",
          },
        },
        {
          type: "line",
          value: 135.35,
          stroke: "#D21E75",
          lineDash: [2, 4],
          label: {
            text: "135.3",
            placement: "right",
            fontSize: 12,
            color: "#000000",
          },
        },
        {
          type: "line",
          value: 123.97,
          stroke: "#D21E75",
          lineDash: [2, 4],
          label: {
            text: "124.0",
            placement: "right",
            fontSize: 12,
            color: "#01c185",
          },
        },
      ],
    },
  },
};

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

const chart = AgCharts.create(options);

{
    crossLines: [
        {
            type: 'range',
            range: [new Date(2019, 4, 1), new Date(2019, 6, 1)],
            strokeWidth: 0,
            fill: '#7290C4',
            fillOpacity: 0.4,
            label: {
                text: 'Price Peak',
                placement: 'top',
                fontSize: 14,
            },
        },
    ],
}

In this configuration:

Properties such as stroke, strokeWidth, and fill are used to customise the Cross Line.
A label is added, customised and placed in relation to the Cross Line. See Label Placement for more details.

Label Placement Copy Link

Use label.placement to choose where a label sits relative to its Cross Line. The default is top.

main.ts

import {
  AgCartesianChartOptions,
  AgCartesianCrossLineLabelPlacement,
  AgCharts,
  CrossLinesModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
  TimeAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

ModuleRegistry.registerModules([
  CrossLinesModule,
  LineSeriesModule,
  NumberAxisModule,
  TimeAxisModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "Monthly Revenue",
  },
  series: [
    {
      type: "line",
      xKey: "month",
      yKey: "revenue",
      yName: "Revenue",
    },
  ],
  axes: {
    x: {
      type: "time",
      crossLines: [
        {
          type: "line",
          value: new Date(2025, 9, 1),
          label: { text: "Launch", placement: "left-top" },
        },
        {
          type: "range",
          enabled: false,
          range: [new Date(2025, 5, 1), new Date(2025, 7, 1)],
          label: { text: "Promotion", placement: "top" },
        },
      ],
    },
    y: {
      type: "number",
      title: {
        text: "Revenue (£k)",
      },
      crossLines: [
        {
          type: "line",
          enabled: false,
          value: 250,
          label: { text: "Target", placement: "top" },
        },
        {
          type: "range",
          range: [180, 210],
          label: { text: "Baseline", placement: "inside-top-left" },
        },
      ],
    },
  },
};

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

const chart = AgCharts.create(options);

function setPlacement(
  axis: "x" | "y",
  type: "line" | "range",
  placement: AgCartesianCrossLineLabelPlacement,
) {
  for (const crossLine of options.axes![axis]!.crossLines!) {
    if (crossLine.type === type) {
      crossLine.label!.placement = placement;
    }
  }

  chart.update(options);
}

function toggleCrossLine(
  axis: "x" | "y",
  type: "line" | "range",
  enabled: boolean,
) {
  for (const crossLine of options.axes![axis]!.crossLines!) {
    if (crossLine.type === type) {
      crossLine.enabled = enabled;
    }
  }

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setPlacement = setPlacement;
  (<any>window).toggleCrossLine = toggleCrossLine;
}

{
    axes: {
        x: {
            type: 'time',
            crossLines: [
                {
                    type: 'line',
                    value: new Date(2025, 9, 1),
                    label: { text: 'Launch', placement: 'left-top' },
                },
            ],
        },
        y: {
            type: 'number',
            crossLines: [
                {
                    type: 'range',
                    range: [180, 210],
                    label: { text: 'Baseline', placement: 'inside-top-left' },
                },
            ],
        },
    },
}

In this example:

Use the checkboxes to show a line and a range on each axis, and the dropdowns to change their placements. Each dropdown lists the placements that apply to that Cross Line.
The first part of a placement names the edge the label sits against, and the second positions it along that edge. For example, top-left sits above the Cross Line aligned to its left, while left-top sits beside its left edge aligned to its top.
Some placements apply to only one axis, such as top-left for a y-axis line and left-top for an x-axis line.
start and end resolve to left and right, and are mirrored when RTL Layout is enabled.
Providing placement as an ordered array lets the label fall back to the next placement when it collides or doesn't fit.

Fitting Long Labels Copy Link

There are a number of ways to handle long labels which do not fit within the series area or exceed a provided maxWidth or maxHeight.

main.ts

import {
  AgCartesianChartOptions,
  AgCharts,
  CrossLinesModule,
  LineSeriesModule,
  ModuleRegistry,
  NumberAxisModule,
  TextWrap,
  TimeAxisModule,
} from "ag-charts-community";
import { getData } from "./data";

ModuleRegistry.registerModules([
  CrossLinesModule,
  LineSeriesModule,
  NumberAxisModule,
  TimeAxisModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "Monthly Revenue",
  },
  series: [
    {
      type: "line",
      xKey: "month",
      yKey: "revenue",
      yName: "Revenue",
    },
  ],
  axes: {
    x: {
      type: "time",
      crossLines: [
        {
          type: "range",
          range: [new Date(2025, 5, 1), new Date(2025, 7, 1)],
          label: {
            text: "Summer Promotion: Reduced Pricing in All Stores",
            placement: "inside-top",
            maxWidth: 120,
            maxHeight: 60,
          },
        },
      ],
    },
    y: {
      type: "number",
      title: {
        text: "Revenue (£k)",
      },
      crossLines: [
        {
          type: "line",
          value: 250,
          label: {
            text: "Annual Revenue Target: £250k per Month",
            placement: "top-left",
            maxWidth: 120,
            maxHeight: 60,
          },
        },
      ],
    },
  },
};

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

const chart = AgCharts.create(options);

function setMaxWidth(event: Event) {
  const value = Number((event.target as HTMLInputElement).value);
  document.getElementById("maxWidthValue")!.textContent = String(value);
  options.axes!.x!.crossLines![0].label!.maxWidth = value;
  options.axes!.y!.crossLines![0].label!.maxWidth = value;

  chart.update(options);
}

function setMaxHeight(event: Event) {
  const value = Number((event.target as HTMLInputElement).value);
  document.getElementById("maxHeightValue")!.textContent = String(value);
  options.axes!.x!.crossLines![0].label!.maxHeight = value;
  options.axes!.y!.crossLines![0].label!.maxHeight = value;

  chart.update(options);
}

function setWrapping(value: string) {
  options.axes!.x!.crossLines![0].label!.wrapping = value as TextWrap;
  options.axes!.y!.crossLines![0].label!.wrapping = value as TextWrap;

  chart.update(options);
}

function setMinimumFontSize(event: Event) {
  const value = Number((event.target as HTMLInputElement).value);
  document.getElementById("minimumFontSizeValue")!.textContent = String(value);
  options.axes!.x!.crossLines![0].label!.minimumFontSize = value;
  options.axes!.y!.crossLines![0].label!.minimumFontSize = value;

  chart.update(options);
}

function setTruncate(value: string) {
  options.axes!.x!.crossLines![0].label!.truncate = value === "enabled";
  options.axes!.y!.crossLines![0].label!.truncate = value === "enabled";

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setMaxWidth = setMaxWidth;
  (<any>window).setMaxHeight = setMaxHeight;
  (<any>window).setWrapping = setWrapping;
  (<any>window).setMinimumFontSize = setMinimumFontSize;
  (<any>window).setTruncate = setTruncate;
}

{
    crossLines: [
        {
            type: 'range',
            range: [new Date(2025, 5, 1), new Date(2025, 7, 1)],
            label: {
                text: 'Summer Promotion: Reduced Pricing in All Stores',
                placement: 'inside-top',
                maxWidth: 120,
                maxHeight: 60,
            },
        },
    ],
}

In this example:

Use the controls to see how the labels wrap, shrink and truncate.
A label that exceeds maxWidth or maxHeight or does not fit within the series area, wraps according to wrapping, shrinks towards minimumFontSize, then is truncated if truncate is enabled. See Series Label Collision Avoidance for details.

Polar Axes Cross Lines Copy Link

Cross Lines are also available for Polar Axes. They share the line and range options of Cartesian Cross Lines, but the label options differ by axis: radius axis labels are positioned with positionAngle, and angle axis labels support the common label options only.

Polar Cross Lines are not included in CrossLinesModule. Register PolarCrossLinesModule separately when using module imports.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AngleCategoryAxisModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  PolarCrossLinesModule,
  RadarLineSeriesModule,
  RadiusNumberAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AngleCategoryAxisModule,
  AnimationModule,
  CrosshairModule,
  PolarCrossLinesModule,
  LegendModule,
  RadarLineSeriesModule,
  RadiusNumberAxisModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Skill Analysis",
  },
  series: [
    {
      type: "radar-line",
      angleKey: "skill",
      radiusKey: "value",
    },
  ],
  axes: {
    angle: {
      type: "angle-category",
      shape: "circle",
      crossLines: [
        {
          type: "range",
          range: ["Technical Skills", "Communication"],
          label: {
            text: "Valuable Skills",
          },
        },
      ],
    },
    radius: {
      type: "radius-number",
      shape: "circle",
      crossLines: [
        {
          type: "line",
          value: 6,
          stroke: "red",
          label: {
            text: "Minimal\nRequirement",
            positionAngle: 180,
          },
        },
      ],
    },
  },
};

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

const chart = AgCharts.create(options);

{
    axes: {
        angle: {
            type: 'angle-category',
            shape: 'circle',
            crossLines: [
                {
                    type: 'range',
                    range: ['Technical Skills', 'Communication'],
                    label: {
                        text: 'Valuable Skills',
                    },
                },
            ],
        },
        radius: {
            type: 'radius-number',
            shape: 'circle',
            crossLines: [
                {
                    type: 'line',
                    stroke: 'red',
                    value: 6,
                    label: {
                        text: 'Minimal\nRequirement',
                        positionAngle: 180,
                    },
                },
            ],
        },
    },
}

Theming Cross Lines Copy Link

Theme overrides style every Cross Line on an axis type. Add a line or range object to style only the Cross Lines of that type.

{
    theme: {
        overrides: {
            common: {
                axes: {
                    number: {
                        crossLines: {
                            strokeWidth: 2,
                            line: { stroke: '#d62728', lineDash: [4, 4] },
                            range: { fill: '#7290C4', fillOpacity: 0.2 },
                        },
                    },
                },
            },
        },
    },
}

In this configuration:

strokeWidth applies to every Cross Line.
The line and range options take precedence over the options for every Cross Line, and options set on a Cross Line take precedence over both.

API Reference Copy Link

type required 'line': Renders the Cross Line as a single line positioned at `value`.
value required AxisValue: The data value at which the line should be positioned.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgCartesianCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

type required 'range': Renders the Cross Line as a shaded band spanning `range`.
range required [AxisValue, AxisValue]: The `[start, end]` data values bounding the shaded region.
fill AgCssColorOrRef: The colour to use for the fill of the range. A colour string, or a theme-colour reference object.
fillOpacity Opacity: The opacity of the fill for the range.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgCartesianCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

type required 'line': Renders the Cross Line as a single line positioned at `value`.
value required AxisValue: The data value at which the line should be positioned.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgBaseCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

type required 'range': Renders the Cross Line as a shaded band spanning `range`.
range required [AxisValue, AxisValue]: The `[start, end]` data values bounding the shaded region.
fill AgCssColorOrRef: The colour to use for the fill of the range. A colour string, or a theme-colour reference object.
fillOpacity Opacity: The opacity of the fill for the range.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgBaseCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

type required 'line': Renders the Cross Line as a single line positioned at `value`.
value required AxisValue: The data value at which the line should be positioned.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgRadiusCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

type required 'range': Renders the Cross Line as a shaded band spanning `range`.
range required [AxisValue, AxisValue]: The `[start, end]` data values bounding the shaded region.
fill AgCssColorOrRef: The colour to use for the fill of the range. A colour string, or a theme-colour reference object.
fillOpacity Opacity: The opacity of the fill for the range.
id string: A user-supplied identifier for the Cross Line, surfaced as `crossLineId` in callback and event params. Defaults to an internally generated identifier.
enabled boolean: Whether to show the Cross Line.
stroke AgCssColorOrRef: The colour of the stroke for the lines. A colour string, or a theme-colour reference object.
strokeWidth PixelSize: The width in pixels of the stroke for the lines.
strokeOpacity Opacity: The opacity of the stroke for the lines.
lineDash PixelSize[]: Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels.
label AgRadiusCrossLineLabelOptions: Configuration for the Cross Line label.
listeners AgCrossLineListeners: A map of event names to listeners.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsCross Lines

Adding Cross Lines Copy Link

Customising Cross Lines Copy Link

Label Placement Copy Link

Fitting Long Labels Copy Link

Polar Axes Cross Lines Copy Link

Theming Cross Lines Copy Link

API Reference Copy Link