JavaScript ChartsPie Series

Version 14.2.0

A Pie Series displays categorical data as proportional slices within a circle.

Simple Pie Copy Link

main.ts

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

ModuleRegistry.registerModules([LegendModule, PieSeriesModule]);

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

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 Pie Series, use the pie series type.

{
    series: [{ type: 'pie', angleKey: 'amount', legendItemKey: 'asset' }],
}

In this configuration:

angleKey determines the angle of each pie sector. The total of all values will correspond to the full pie.
legendItemKey configures the names to be used in the legend for each sector.

Labels Copy Link

The Pie Series supports two types of label related to individual sectors.

Callout labels are displayed adjacent to each sector, connected with callout line.
Sector labels are displayed inside each sector.

main.ts

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

ModuleRegistry.registerModules([LegendModule, PieSeriesModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  series: [
    {
      type: "pie",
      angleKey: "amount",
      calloutLabelKey: "asset",
      sectorLabelKey: "amount",
      sectorLabel: {
        color: "white",
        fontWeight: "bold",
        formatter: ({ value }) => `$${(value / 1000).toFixed(0)}K`,
      },
    },
  ],
};

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 },
  ];
}

{
    series: [
        {
            type: 'pie',
            angleKey: 'amount',
            calloutLabelKey: 'asset',
            sectorLabelKey: 'amount',
            sectorLabel: {
                color: 'white',
                fontWeight: 'bold',
            },
        },
    ],
}

In this configuration:

calloutLabelKey defines the variable used for the callout labels. This is also used in the Legend if no legendItemKey is provided, and in the Tooltips.
sectorLabelKey defines the variable used for the sector labels.

By default, callout labels won't be displayed for sectors with a value of 0. Set calloutLabel.minAngle = 0 to show these.

It is possible to customise the text displayed in these labels by using the calloutLabel.formatter and sectorLabel.formatter. These functions receive a single object as a parameter containing the options and datum associated with a pie sector, and should return a string.

See Series Labels for how to constrain callout and sector labels to the space available.

Also see the API reference for options to customise calloutLabel, calloutLine and sectorLabel, as well as other series customisations.

Variable Sector Radius Copy Link

It is possible to visualise a second variable in the Pie Series by using the radiusKey to vary the radius of a sector based on the values. This is also known as a Rose Chart.

main.ts

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

ModuleRegistry.registerModules([LegendModule, PieSeriesModule]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Portfolio Composition",
  },
  subtitle: {
    text: "Showing Annual Yield",
  },
  series: [
    {
      type: "pie",
      angleKey: "amount",
      radiusKey: "yield",
      legendItemKey: "asset",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

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

{
    series: [
        {
            type: 'pie',
            radiusKey: 'yield',
            angleKey: 'amount',
            legendItemKey: 'asset',
        },
    ],
}

Pie Chart Examples Copy Link

See more Pie Chart examples in the AG Charts Gallery.

Pie Chart Example

Pie Chart With Variable Radius Example

Pie Chart In A Donut Example

API Reference Copy Link

Properties available on the AgPieSeriesOptions interface.

type required 'pie': Configuration for Pie Series.
angleKey required DatumKey: The key to use to retrieve angle values from the data.
title AgPieTitleOptions: Configuration for the series title.
calloutLabel AgPieSeriesLabelOptions: Configuration for the labels used outside the sectors.
sectorLabel AgPieSeriesSectorLabelOptions: Configuration for the labels used inside the sectors.
calloutLine AgPieSeriesCalloutOptions: 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 pie 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.
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.
cornerRadius PixelSize: Apply rounded corners to each sector.
sectorSpacing PixelSize: The spacing between Pie 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 pie 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 pie 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 ChartsPie Series

Simple Pie Copy Link

Labels Copy Link

Variable Sector Radius Copy Link

Pie Chart Examples Copy Link

API Reference Copy Link