JavaScript ChartsLine Series

Version 14.2.0

A Line Series visualises continuous data, and is typically used to see trends or fluctuations over time.

Simple Line Copy Link

main.ts

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

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

const options: AgChartOptions = {
  title: {
    text: "Annual Fuel Expenditure",
  },
  data: getData(),
  series: [
    {
      type: "line",
      xKey: "quarter",
      yKey: "petrol",
      yName: "Petrol",
    },
    {
      type: "line",
      xKey: "quarter",
      yKey: "diesel",
      yName: "Diesel",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      quarter: "Q1",
      petrol: 200,
      diesel: 100,
    },
    {
      quarter: "Q2",
      petrol: 300,
      diesel: 130,
    },
    {
      quarter: "Q3",
      petrol: 350,
      diesel: 160,
    },
    {
      quarter: "Q4",
      petrol: 400,
      diesel: 200,
    },
  ];
}

To create a Line Series, use the line series type. If no type is provided, a Line Series will be created by default.

{
    series: [
        { type: 'line', xKey: 'quarter', yKey: 'petrol', yName: 'Petrol' },
        { type: 'line', xKey: 'quarter', yKey: 'diesel', yName: 'Diesel' },
    ],
}

In this configuration:

xKey defines the categories, and is mapped to the Category Axis.
yKey provides the numerical values, corresponding to the Number Axis.
yName configures display names, reflected in Tooltip Titles and Legend Items.

Customisation Copy Link

It is possible to customise the appearance of the line, labels and markers for each series.

main.ts

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

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

const options: AgChartOptions = {
  title: {
    text: "Annual Fuel Expenditure",
  },
  data: getData(),
  series: [
    {
      type: "line",
      xKey: "quarter",
      yKey: "petrol",
      yName: "Petrol",
      strokeWidth: 4,
      marker: {
        enabled: false,
      },
    },
    {
      type: "line",
      xKey: "quarter",
      yKey: "diesel",
      yName: "Diesel",
      stroke: "black",
      label: {
        fontWeight: "bold",
        formatter: ({ value }) => value.toFixed(0),
      },
      marker: {
        fill: "orange",
        size: 10,
        stroke: "black",
        strokeWidth: 3,
        shape: "diamond",
      },
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      quarter: "Q1",
      petrol: 200,
      diesel: 100,
    },
    {
      quarter: "Q2",
      petrol: 300,
      diesel: 130,
    },
    {
      quarter: "Q3",
      petrol: 350,
      diesel: 160,
    },
    {
      quarter: "Q4",
      petrol: 400,
      diesel: 200,
    },
  ];
}

Note that the Legend automatically reflects the customisation of the series and markers.

Labels Copy Link

Labels can be displayed above each data point. Use the label option to enable and style the labels.

{
    series: [
        {
            // ...
            label: {
                enabled: true,
                fontWeight: 'bold',
            },
        },
    ],
}

Please see the API Reference for a list of all available label options.

Markers Copy Link

Markers are displayed by default in the Line Series. Use the marker option to style or disable the markers.

{
    series: [
        {
            // ...
            marker: {
                fill: 'orange',
                size: 10,
                stroke: 'black',
                strokeWidth: 3,
                shape: 'diamond',
            },
        },
    ],
}

Please see the Series Markers page for more information or the API Reference for a list of all available marker options.

Interpolation Copy Link

A straight line is used to connect points by default in the Line Series. Use the interpolation option to change the line style.

main.ts

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

let interpolationType: "linear" | "smooth" | "step" = "smooth";
let stepPosition: "start" | "middle" | "end" = "end";
ModuleRegistry.registerModules([
  CategoryAxisModule,
  LegendModule,
  LineSeriesModule,
  NumberAxisModule,
]);

const options: AgCartesianChartOptions = {
  title: {
    text: "2023 Average Temperatures",
  },
  subtitle: {
    text: "Oxford, UK",
  },
  data: getData(),
  series: [
    {
      type: "line",
      xKey: "month",
      xName: "Month",
      yKey: "min",
      yName: "Min Temperature",
      interpolation: { type: "smooth" },
    },
    {
      type: "line",
      xKey: "month",
      xName: "Month",
      yKey: "max",
      yName: "Max Temperature",
      interpolation: { type: "smooth" },
    },
  ],
};

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

const chart = AgCharts.create(options);

function typeChange(event: Event) {
  interpolationType = (event.target as HTMLInputElement).value as
    | "linear"
    | "smooth"
    | "step";
  const stepPositionGroup = document.getElementById(
    "stepPositionGroup",
  ) as HTMLFieldSetElement;
  stepPositionGroup.disabled = interpolationType !== "step";
  options.series?.forEach((series) => {
    (series as AgLineSeriesOptions).interpolation =
      interpolationType === "step"
        ? { type: "step", position: stepPosition }
        : { type: interpolationType };
  });

  chart.update(options);
}

function positionChange(event: Event) {
  stepPosition = (event.target as HTMLInputElement).value as
    | "start"
    | "middle"
    | "end";
  options.series?.forEach((series) => {
    (series as AgLineSeriesOptions).interpolation = {
      type: "step",
      position: stepPosition,
    };
  });

  chart.update(options);
}

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

data.ts

// Source: https://www.metoffice.gov.uk/pub/data/weather/uk/climate/stationdata/oxforddata.txt
export function getData() {
  return [
    { month: "January", max: 8.5, min: 2.6 },
    { month: "February", max: 10.4, min: 3.0 },
    { month: "March", max: 10.9, min: 4.7 },
    { month: "April", max: 13.7, min: 5.0 },
    { month: "May", max: 18.2, min: 8.4 },
    { month: "June", max: 23.6, min: 12.2 },
    { month: "July", max: 21.3, min: 13.0 },
    { month: "August", max: 21.9, min: 13.1 },
    { month: "September", max: 22.6, min: 13.2 },
    { month: "October", max: 17.0, min: 9.7 },
    { month: "November", max: 11.1, min: 4.9 },
    { month: "December", max: 10.2, min: 5.2 },
  ];
}

{
    series: [
        {
            // ...
            interpolation: {
                type: 'smooth',
            },
        },
    ],
}

Please see the API Reference for a list of all available interpolation options.

Data Copy Link

Missing Data Copy Link

main.ts

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

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

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "People Born",
  },
  subtitle: {
    text: "2008-2020",
  },
  series: [
    {
      type: "line",
      xKey: "year",
      yKey: "visitors",
      connectMissingData: false,
    },
  ],
};

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

const chart = AgCharts.create(options);

function toggleConnectMissingData() {
  options.series = (options.series as Array<AgLineSeriesOptions>).map(
    (series) => ({
      ...series,
      connectMissingData: !series.connectMissingData,
    }),
  );

  chart.update(options);
}

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

data.ts

export function getData(): any[] {
  return [
    {
      year: "2008",
      visitors: 191000,
    },
    {
      year: "2009",
      visitors: 45000,
    },
    {
      year: "2010",
      visitors: 100000,
    },
    {
      year: "2011",
      visitors: null,
    },
    {
      year: "2012",
      visitors: 78000,
    },
    {
      year: "2013",
      visitors: 136000,
    },
    {
      year: "2014",
      visitors: undefined,
    },
    {
      year: "2015",
      visitors: NaN,
    },
    {
      year: "2016",
      visitors: 67000,
    },
    {
      year: "2017",
      visitors: Infinity,
    },
    {
      year: "2018",
      visitors: 174000,
    },
    {
      year: "2019",
      visitors: 76000,
    },
    {
      year: "2020",
      visitors: 56000,
    },
  ];
}

Data points with a yKey value of positive or negative Infinity, null, undefined or NaN will be rendered as a gap in the line. Set connectMissingData: true to draw a connecting line between points either side of a missing point.
Data points with invalid xKey values will be ignored.

Continuous Data Copy Link

By default, the Line series uses a Category Axis to plot the xKey values, but this can be changed if you have continuous data, such as trends over time.

main.ts

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

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

const options: AgChartOptions = {
  title: {
    text: "Temperature Readings",
  },
  series: [
    {
      type: "line",
      data: getLoungeData(),
      xKey: "time",
      yKey: "sensor",
      yName: "Lounge",
    },
    {
      type: "line",
      data: getOfficeData(),
      xKey: "time",
      yKey: "sensor",
      yName: "Office",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
    },
    y: {
      type: "number",
      label: {
        format: "#{.1f} °C",
      },
    },
  },
};

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

const chart = AgCharts.create(options);

data.ts

export function getLoungeData() {
  return [
    {
      time: new Date("01 Jan 2020 13:25:30 GMT"),
      sensor: 25,
    },
    {
      time: new Date("01 Jan 2020 13:26:30 GMT"),
      sensor: 24,
    },
    {
      time: new Date("01 Jan 2020 13:27:30 GMT"),
      sensor: 24,
    },
    {
      time: new Date("01 Jan 2020 13:28:30 GMT"),
      sensor: 23,
    },
    {
      time: new Date("01 Jan 2020 13:29:30 GMT"),
      sensor: 22.5,
    },
    {
      time: new Date("01 Jan 2020 13:30:30 GMT"),
      sensor: 21.5,
    },
    {
      time: new Date("01 Jan 2020 13:31:30 GMT"),
      sensor: 22.5,
    },
  ];
}

export function getOfficeData() {
  return [
    {
      time: Date.parse("01 Jan 2020 13:25:00 GMT"),
      sensor: 21,
    },
    {
      time: Date.parse("01 Jan 2020 13:26:00 GMT"),
      sensor: 22,
    },
    {
      time: Date.parse("01 Jan 2020 13:28:00 GMT"),
      sensor: 22,
    },
    {
      time: Date.parse("01 Jan 2020 13:29:00 GMT"),
      sensor: 23,
    },
    {
      time: Date.parse("01 Jan 2020 13:30:00 GMT"),
      sensor: 24,
    },
    {
      time: Date.parse("01 Jan 2020 13:31:00 GMT"),
      sensor: 24,
    },
    {
      time: Date.parse("01 Jan 2020 13:32:00 GMT"),
      sensor: 24.5,
    },
    {
      time: Date.parse("01 Jan 2020 13:33:00 GMT"),
      sensor: 24.5,
    },
  ];
}

Time can be provided as a Date object, a number which is interpreted as timestamps derived from Unix time or an ISO 8601 string.
See Time Axes for more information about the different time axes available.
All time axes automatically select an appropriate label format depending on the time span of the data, making a best-effort attempt to prevent the labels from overlapping.

See Axes Types for more information on using a Time Axis or a Number Axis.

Line Chart Examples Copy Link

See more Line Chart examples in the AG Charts Gallery.

Line Chart Example

Line Chart With Gaps Example

Line Chart with Multiple Series Example

Line Chart With Time Axis Example

Line Chart With Large Data Example

Line Chart With Labels Example

API Reference Copy Link

Properties available on the AgLineSeriesOptions interface.

type required 'line': Configuration for the Line Series.
xKey required DatumKey: The key to use to retrieve x-values from the data.
yKey required DatumKey: The key to use to retrieve y-values from the data.
errorBar AgErrorBarOptions: Configuration for the Error Bars.
normalizedTo number: The number to normalise the line stacks to. For example, if `normalizedTo` is set to `100`, the stacks will all be scaled proportionally so that their total height is always 100.
stacked boolean: An option indicating if the lines should be stacked.
stackGroup string: An ID to be used to group stacked items.
id string default: auto-generated value: Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
context ContextDefault: Context object to use in callbacks.
data DatumDefault[]: The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean: Whether to display the series.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
selection AgSelectionOptions: Configuration for data selection.
nodeClickRange InteractionRange: Range from a node that a click triggers the listener.
showInLegend boolean: Whether to include the series in the legend.
listeners AgSeriesListeners: A map of event names to event listeners.
xKeyAxis string default: 'x': The key of the x-axis to which this series is bound.
yKeyAxis string default: 'y': The key of the y-axis to which this series is bound.
xName string: A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yName string: A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
legendItemName string: Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
styler Styler: Function used to return formatting for entire series, based on the given parameters.
marker AgSeriesMarkerOptions: Configuration for the markers used in the series.
interpolation AgInterpolationType: Configuration for the line used in the series.
title string: The title to use for the series. Defaults to `yName` if it exists, or `yKey` if not.
label AgLineSeriesLabelOptions: Configuration for the labels shown on top of data points.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
connectMissingData boolean: Set to `true` to connect across missing data points.
highlight AgMultiSeriesHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
segmentation AgSeriesSegmentation: Configuration for styling series as separate segments.
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.
showInMiniChart boolean: Whether to include the series in the Mini Chart.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsLine Series

Simple Line Copy Link

Customisation Copy Link

Labels Copy Link

Markers Copy Link

Interpolation Copy Link

Data Copy Link

Missing Data Copy Link

Continuous Data Copy Link

Line Chart Examples Copy Link

API Reference Copy Link