---
title: "Secondary Axes"
framework: javascript
version: "14.1.0"
---

# Secondary Axes

Secondary axes are typically used to compare data sets with different scales, with extra axes usually located on the opposite side of the chart.

## Creating a Secondary Axis

The easiest way to create a secondary axis is by assigning a series to an axis key with the `series[].yKeyAxis` property.

If a series provides a `yKeyAxis` value, and no axis exists for that key, a new axis with default properties will be automatically created.

The second `y` axis will be positioned to the `'right'` by default.

This allows you to create and use a secondary axis without any explicit axis configuration.

#### Secondary y-axis

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

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

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Cattle Holdings and Beef Exports (UK)",
    fontSize: 18,
  },
  subtitle: {
    text: "Source: Department for Environment, Food & Rural Affairs",
  },
  series: [
    {
      type: "bar",
      xKey: "year",
      yKey: "male",
      yName: "Male cattle",
    },
    {
      type: "bar",
      xKey: "year",
      yKey: "female",
      yName: "Female cattle",
    },
    {
      type: "line",
      xKey: "year",
      yKey: "exportedTonnes",
      yName: "Beef exports",
      yKeyAxis: "ySecondary",
      strokeWidth: 5,
      marker: {
        enabled: false,
      },
    },
  ],
  axes: {
    y: {
      type: "number",
      position: "left",
      title: {
        text: "Number of cattle",
      },
      label: {
        formatter: (params) => {
          return params.value / 1000 + "M";
        },
      },
    },
    ySecondary: {
      type: "number",
      position: "right",
      title: {
        text: "Exports (tonnes)",
      },
      label: {
        formatter: (params) => {
          return params.value / 1000 + "k";
        },
      },
    },
  },
  legend: {
    item: {
      marker: {
        shape: "square",
        strokeWidth: 0,
      },
    },
  },
};

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

const chart = AgCharts.create(options);
```

[Live example: Secondary y-axis](https://www.ag-grid.com/charts/typescript/axes-secondary/examples/multiple-axes)

In this example:

- The `bar` series do not specify a `yKeyAxis`, so they are linked to the default `y` axis.
- The `line` series specifies `yKeyAxis: 'ySecondary'`, which automatically creates a new secondary axis on the right.
- Any number of `y` axes can be created in this way and the same concept applies to x-axes using the `xKeyAxis` property.

```js
{
    series: [
        // These two series are linked to the default 'y' axis
        { type: 'bar', xKey: 'year', yKey: 'male' },
        { type: 'bar', xKey: 'year', yKey: 'female' },

        // This series is linked to a new, automatically created 'ySecondary' axis
        {
            type: 'line',
            xKey: 'year',
            yKey: 'exportedTonnes',
            yKeyAxis: 'ySecondary',
        },
    ],
}
```

## Configuring Axes

Automatic creation is useful in many cases, but explicit axis configuration is often required, for example to add a title or change its position.

To do this, the configured axes are declared in the `axes` property. The keys used here must match the keys used by the `yKeyAxis` property on the series.

```js
{
    axes: {
        y: {
            // This configures the default y-axis
            type: 'number',
            position: 'left',
            title: { text: 'Number of cattle' },
        },
        ySecondary: {
            // This configures the 'ySecondary' used by the line series
            type: 'number',
            position: 'right',
            title: { text: 'Exports (tonnes)' },
        },
    },
}
```

## Custom Axis Keys

The above example used the default `y` key and an additional key of `ySecondary`.

To increase readability, especially when dealing with multiple axes with distinct meanings, more descriptive axis keys should be used.

Series are linked to axes by supplying an axis key in the series configuration using the `xKeyAxis`, `yKeyAxis` and similar properties.

The axis key supplied to the series does not need to be used in the `axes` options if no customisation is required.

```js
{
    series: [
        { type: 'bar', xKey: 'month', yKey: 'profit', yKeyAxis: 'profit' },
        { type: 'line', xKey: 'month', yKey: 'revenue', yKeyAxis: 'revenue' },
    ],
    axes: {
        revenue: { type: 'number', position: 'right', title: { text: 'revenue' } },
        profit: { type: 'number', position: 'left', title: { text: 'profit' } },
    },
}
```

In this configuration:

- The `yKey` values of the first series are plotted against the `profit` axis on the left, whilst the `yKey` values of the second series are plotted against the `revenue` axis on the right.
- Series default to the `x` and `y` axis keys when not specified, so `series[].xKeyAxis` is not required.
- `axes.x` is not required because no customisation is needed for the default x-axis.
- There is no `axes.y` in this chart as all series have specified a different `yKeyAxis`.

Specifying `type` is not required but is recommended for type-checking and validation.

The `position` property is also optional. The first secondary y-axis will automatically be placed on the right, with subsequent axes alternating to the left. Without explicit `position` or series axis key properties, the chart may misidentify or misplace axes, so specifying `position` is recommended.