Angular ChartsSecondary 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 Copy Link

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.

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.

{
    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 Copy Link

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.

{
    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 Copy Link

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.

{
    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.