JavaScript ChartsDonut Series

Version 14.2.0

A Donut Series has all the benefits of a Pie Series and allows displaying multiple datasets in a single chart.

Simple Donut Copy Link

main.ts

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

ModuleRegistry.registerModules([DonutSeriesModule, LegendModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  series: [
    {
      type: "donut",
      calloutLabelKey: "asset",
      angleKey: "amount",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { asset: "Stocks", amount: 60000 },
    { asset: "Bonds", amount: 40000 },
    { asset: "Cash", amount: 7000 },
    { asset: "Real Estate", amount: 5000 },
    { asset: "Commodities", amount: 3000 },
  ];
}

To create a Donut Series, use the donut series type.

{
    series: [
        {
            type: 'donut',
            calloutLabelKey: 'asset',
            angleKey: 'amount',
        },
    ],
}

An optional innerRadiusRatio can be provided which should be a value between 0 and 1 and defines the radius of the inner circle as a ratio of the outer radius of the chart.

Labels Copy Link

The Donut Series supports the same callout and sector labels as the Pie Series, including the label fitting options that constrain a label to the space available.

Inner Labels Copy Link

main.ts

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

ModuleRegistry.registerModules([DonutSeriesModule, LegendModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  series: [
    {
      type: "donut",
      calloutLabelKey: "asset",
      angleKey: "amount",
      innerRadiusRatio: 0.9,
      innerLabels: [
        {
          text: "Total Investment",
          fontWeight: "bold",
        },
        {
          text: "$100,000",
          spacing: 4,
          fontSize: 40,
          color: "green",
        },
      ],
      innerCircle: {
        fill: "#c9fdc9",
      },
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { asset: "Stocks", amount: 60000 },
    { asset: "Bonds", amount: 40000 },
    { asset: "Cash", amount: 7000 },
    { asset: "Real Estate", amount: 5000 },
    { asset: "Commodities", amount: 3000 },
  ];
}

The innerLabels property can be used to put several lines of text in the space inside a Donut Series.

The colour of the centre area can be changed by using innerCircle.

{
    series: [
        {
            // ...
            innerLabels: [
                {
                    text: 'Total Investment',
                    fontWeight: 'bold',
                },
                {
                    text: '$100,000',
                    spacing: 4,
                    fontSize: 44,
                    color: 'green',
                },
            ],
            innerCircle: {
                fill: '#c9fdc9',
            },
        },
    ],
}

Multiple Donuts Copy Link

main.ts

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

ModuleRegistry.registerModules([DonutSeriesModule, LegendModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  subtitle: {
    text: "Versus Previous Year",
  },
  series: [
    {
      type: "donut",
      title: {
        text: "Previous Year",
        showInLegend: true,
      },
      calloutLabelKey: "asset",
      angleKey: "previousYear",
      outerRadiusRatio: 1,
      innerRadiusRatio: 0.9,
    },
    {
      type: "donut",
      title: {
        text: "Current Year",
        showInLegend: true,
      },
      calloutLabelKey: "asset",
      angleKey: "currentYear",
      outerRadiusRatio: 0.6,
      innerRadiusRatio: 0.2,
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { asset: "Stocks", previousYear: 70000, currentYear: 40000 },
    { asset: "Bonds", previousYear: 30000, currentYear: 60000 },
    { asset: "Cash", previousYear: 5000, currentYear: 7000 },
    { asset: "Real Estate", previousYear: 8000, currentYear: 5000 },
    { asset: "Commodities", previousYear: 4500, currentYear: 3000 },
  ];
}

To render multiple Donut Series in a single chart without overlapping, set an outerRadiusRatio in conjunction with an innerRadiusRatio.

{
    series: [
        {
            // outer series
            // ...
            outerRadiusRatio: 1, // the default
            innerRadiusRatio: 0.9,
            title: { text: 'Previous Year', showInLegend: true },
        },
        {
            // inner series
            // ...
            outerRadiusRatio: 0.6,
            innerRadiusRatio: 0.2,
            title: { text: 'Current Year', showInLegend: true },
        },
    ],
}

In the above configuration:

The difference of 0.3 between the innerRadiusRatio of the outer series and the outerRadiusRatio of the inner series determines the size of the gap between the outer and inner series.
The difference between outerRadiusRatio and innerRadiusRatio for each series determines the thickness of the ring for that series.
The title provided for each series is displayed above the Donut Series if there is space.
Using showInLegend displays the title within the legend item, allowing differentiation between the two series within the legend.

Shared Legend Copy Link

main.ts

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

ModuleRegistry.registerModules([DonutSeriesModule, LegendModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  subtitle: {
    text: "Versus Previous Year",
  },
  series: [
    {
      type: "donut",
      title: {
        text: "Previous Year",
      },
      calloutLabelKey: "asset",
      legendItemKey: "asset",
      angleKey: "previousYear",
      outerRadiusRatio: 1,
      innerRadiusRatio: 0.9,
    },
    {
      type: "donut",
      title: {
        text: "Current Year",
      },
      legendItemKey: "asset",
      showInLegend: false,
      angleKey: "currentYear",
      outerRadiusRatio: 0.6,
      innerRadiusRatio: 0.2,
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { asset: "Stocks", previousYear: 70000, currentYear: 40000 },
    { asset: "Bonds", previousYear: 30000, currentYear: 60000 },
    { asset: "Cash", previousYear: 5000, currentYear: 7000 },
    { asset: "Real Estate", previousYear: 8000, currentYear: 5000 },
    { asset: "Commodities", previousYear: 4500, currentYear: 3000 },
  ];
}

Providing a matching legendItemKey allows synchronising of legend items across multiple Donut Series. When a legend item is clicked, all items with a matching legendItemKey are toggled.

{
    series: [
        {
            // ...
            calloutLabelKey: 'asset',
            legendItemKey: 'asset',
        },
        {
            // ...
            legendItemKey: 'asset',
            showInLegend: false,
        },
    ],
}

Using showInLegend: false for the second series, ensures that there are no duplicate legend items.

Donut Chart Examples Copy Link

See more Donut Chart examples in the AG Charts Gallery.

Donut Chart Example

Donut Chart With Variable Radius Example

Multiple Donut Charts Example

API Reference Copy Link

Properties available on the AgDonutSeriesOptions interface.

type required 'donut': Configuration for Donut Series.
angleKey required DatumKey: The key to use to retrieve angle values from the data.
innerLabels AgDonutInnerLabel[]: Configuration for the text lines to display inside the series.
title AgDonutTitleOptions: Configuration for the series title.
calloutLabel AgDonutSeriesLabelOptions: Configuration for the labels used outside the sectors.
sectorLabel AgDonutSeriesSectorLabelOptions: Configuration for the labels used inside the sectors.
calloutLine AgDonutSeriesCalloutOptions: Configuration for the callout lines used with the labels for the sectors.
fills AgColorType[]: The colours to cycle through for the fills of the sectors. An array of colour strings, or fill objects for gradients, patterns, or images.
strokes CssColor[]: The colours to cycle through for the strokes of the sectors.
fillOpacity Opacity: The opacity of the fill for the sectors.
strokeOpacity Opacity: The opacity of the stroke for the sectors.
strokeWidth PixelSize: The width in pixels of the stroke for the sectors.
rotation Degree: The rotation of the Donut series in degrees.
outerRadiusOffset PixelSize: The offset in pixels of the outer radius of the series.
outerRadiusRatio Ratio: The ratio of the outer radius of the series. Used to adjust the outer radius proportionally to the automatically calculated value.
innerRadiusOffset PixelSize: The offset in pixels of the inner radius of the series.
innerRadiusRatio Ratio default: 0.7: The ratio of the inner radius of the series.
radiusMin number: Override of the automatically determined minimum radiusKey value from the data.
radiusMax number: Override of the automatically determined maximum radiusKey value from the data.
shadow AgDropShadowOptions: Configuration for the shadow used behind the chart series.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
innerCircle AgDonutInnerCircle: Configuration for the area inside the series.
cornerRadius PixelSize: Apply rounded corners to each sector.
sectorSpacing PixelSize: The spacing between Donut sectors.
hideZeroValueSectorsInLegend boolean: Whether items with a value of 0 should be hidden in the legend.
itemStyler Styler: A styler function for adjusting the styling of the Donut sectors.
highlight AgMultiSeriesHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
context ContextDefault: Context object to use in callbacks.
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.
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.
radiusKey DatumKey: The key to use to retrieve radius values from the data.
calloutLabelKey DatumKey: The key to use to retrieve label values from the data.
sectorLabelKey DatumKey: The key to use to retrieve sector label values from the data.
legendItemKey DatumKey: The key to use to retrieve legend item labels from the data. If multiple series share this key they will be merged in the legend.
angleName string: A human-readable description of the angle values. If supplied, this will be passed to the tooltip renderer as one of the parameters.
radiusName string: A human-readable description of the radius values. If supplied, this will be passed to the tooltip renderer as one of the parameters.
calloutLabelName string: A human-readable description of the label values. If supplied, this will be passed to the tooltip renderer as one of the parameters.
sectorLabelName string: A human-readable description of the sector label values. If supplied, this will be passed to the tooltip renderer as one of the parameters.
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.
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.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsDonut Series

Simple Donut Copy Link

Labels Copy Link

Inner Labels Copy Link

Multiple Donuts Copy Link

Shared Legend Copy Link

Donut Chart Examples Copy Link

API Reference Copy Link