Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript Charts: Pie and Doughnut Series

Pie series are useful for illustrating the numerical proportion of data values. The sectors in a pie series show the contribution of individual values to the whole.

For example, a pie series could be used to visualise the market share of each competitor as a proportion of the total.

Basic Configuration

To plot a basic pie all we need is an array of values that will determine the angle of each pie sector. The total of all values will correspond to the full pie.

A minimal pie series configuration is shown below:

series: [{
    type: 'pie',
    angleKey: 'value'
}]

This results in the chart shown below. Note that tooltips show the absolute value of each pie sector.

Labels

We support two types of label related to individual sectors:

  • Call-out labels: displayed adjacent to each sector with a joining line (configured via calloutLabelKey, calloutLabel and calloutLabelLine options).
  • Sector labels: displayed inside each sector (configured via sectorLabelKey and sectorLabel options).

Additionally legend labels and tooltips are derived from the call-out label options.

series: [{
    type: 'pie',
    angleKey: 'value',
+   calloutLabelKey: 'label',
+   sectorLabelKey: 'value',
+   sectorLabel: {
+       color: 'white',
+       fontWeight: 'bold'
+   }
}]

This example demonstrates:

  • Use of calloutLabelKey, enabling:

    • Display of a per-sector callout label.
    • Labels for use in the legend.
    • Tooltips on segment hover including the callout label and sector value.
    • Some callout labels are not displayed, where the sector is smaller than calloutLabel.minAngle (defaults to 20).
  • Use of sectorLabelKey and sectorLabel, enabling:

    • Display of a per-sector inside label.
    • Some sector labels are not displayed, where the sector is too small to fit the label text.
  • Individual sectors can be toggled on and off via the legend.

The calloutLabel.formatter and sectorLabel.formatter functions can be used to change the text value displayed in the labels. They receive a single object as a parameter containing values associated with a pie sector. Please see the API reference for the full list of available properties.

For example, to display the numeric values for a given pie sector in the callout label, you can use the following label formatter function:

series: [{
    ...
    calloutLabel: {
        formatter: ({ datum, calloutLabelKey, angleKey }) => {
            return `${datum[calloutLabelKey]}: ${datum[angleKey]}`;
        }
    }
}]

Please check the API reference below to learn more about calloutLabel, calloutLine and sectorLabel, as well as other series configuration.

Variable Sector Radius

Let's say we have the data for both the market share of mobile operating systems and the level of user satisfaction with each OS. We could represent the satisfaction level as the radius of a sector using the radiusKey config like so:

series: [{
    type: 'pie',
    calloutLabelKey: 'os',
    angleKey: 'share',
    radiusKey: 'satisfaction'
}]

A pie chart where sectors have different radii is also known as a rose chart.

Doughnuts

Pie series can be used to create a doughnut chart by using the innerRadiusOffset config.

series: [{
    type: 'pie',
    calloutLabelKey: 'os',
    angleKey: 'share',
    innerRadiusOffset: -70
}]

The config specifies the offset value from the maximum pie radius which all pie sectors use by default (the maximum pie series radius is determined automatically by the chart depending on the chart's dimensions). -70 in the snippet above means the inner radius of the series should be 70 pixels smaller than the maximum radius.

Alternatively a doughnut chart can be created by using the innerRadiusRatio property. A value between 0.0 and 1.0 should be assigned:

series: [{
    type: 'pie',
    labelKey: 'os',
    angleKey: 'share',
+   innerRadiusRatio: 0.75,
}]

Additional Doughnut Labels

The innerLabels property can be used to put several text lines inside a doughnut chart. The colour of the doughnut's centre can be changed by using innerCircle.

series: [{
    ...
    innerLabels: [
        { text: '85%', fontSize: 48, color: 'green' },
        { text: 'Coverage', margin: 4 }
    ],
    innerCircle: {
        fill: 'lightgreen',
    }
}]

Multiple Doughnuts

As well as the innerRadiusOffset or innerRadiusRatio we can also configure the outerRadiusOffset or outerRadiusRatio. This gives us the ability to render multiple pie series in a single chart without overlapping.

series: [
    {
        type: 'pie',
        outerRadiusRatio: 1,   // 100% (default)
        innerRadiusRatio: 0.8, // 80%
        ...
    },
    {
        type: 'pie',
        outerRadiusRatio: 0.5, // 50%
        innerRadiusRatio: 0.3, // 30%
        ...
    }
]

In the snippet above we configure the outerRadiusRatio of the second (inner) series to be smaller than the innerRadiusRatio of the first (outer) series. The difference of 0.3 (30%) between these offsets will determine the size of the gap between the outer and inner series. The difference between outerRadiusRatio and innerRadiusRatio for each series will determine the thickness of the rings, which will be 20% of the total radius for both series in this case.

The example below uses one pie series to plot the market share of each operating system and another pie series to plot user satisfaction level with each OS:

API Reference

Properties available on the AgPieSeriesOptions<DatumType = any> interface.

angleKey *
string
The key to use to retrieve angle values from the data.
type
'pie'
'pie'
title
AgPieTitleOptions
Configuration for the series title.
title: AgPieTitleOptions;

interface AgPieTitleOptions {
  showInLegend?: boolean;
  // Whether or not the title should be shown. 
  enabled?: boolean;
  // The text to show in the title. 
  text?: string;
  // The font style to use for the title. 
  fontStyle?: FontStyle;
  // The font weight to use for the title. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the title. 
  fontSize?: FontSize;
  // The font family to use for the title. 
  fontFamily?: FontFamily;
  // The colour to use for the title. 
  color?: CssColor;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string
calloutLabel
AgPieSeriesLabelOptions<DatumType>
Configuration for the labels used outside of the sectors.
calloutLabel: AgPieSeriesLabelOptions<DatumType>;

interface AgPieSeriesLabelOptions<DatumType> {
  // Distance in pixels between the callout line and the label text. 
  offset?: PixelSize;
  // Minimum angle in degrees required for a sector to show a label. 
  minAngle?: number;
  // A function that allows the modification of the label text based on input parameters. 
  formatter?: (params: AgPieSeriesLabelFormatterParams<DatumType>) => string;
  // Whether or not the labels should be shown. 
  enabled?: boolean;
  // The font style to use for the labels. 
  fontStyle?: FontStyle;
  // The font weight to use for the labels. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the labels. 
  fontSize?: FontSize;
  // The font family to use for the labels. 
  fontFamily?: FontFamily;
  // The colour to use for the labels. 
  color?: CssColor;
}

type PixelSize = number

interface AgPieSeriesLabelFormatterParams<DatumType> {
  // Datum from the series data array that the label is being rendered for. 
  datum: DatumType;
  // calloutLabelKey as specified on series options. 
  calloutLabelKey?: string;
  // calloutLabelValue as read from series data via the calloutLabelKey property. 
  calloutLabelValue?: string;
  // calloutLabelName as specified on series options. 
  calloutLabelName?: string;
  // sectorLabelKey as specified on series options. 
  sectorLabelKey?: string;
  // sectorLabelValue as read from series data via the sectorLabelKey property. 
  sectorLabelValue?: string;
  // sectorLabelName as specified on series options. 
  sectorLabelName?: string;
  // angleKey as specified on series options. 
  angleKey: string;
  // angleValue as read from series data via the angleKey property. 
  angleValue?: any;
  // angleName as specified on series options. 
  angleName?: string;
  // radiusKey as specified on series options. 
  radiusKey?: string;
  // radiusValue as read from series data via the radiusKey property. 
  radiusValue?: any;
  // radiusName as specified on series options. 
  radiusName?: string;
  // The ID of the series. 
  seriesId: string;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string
sectorLabel
AgPieSeriesSectorLabelOptions<DatumType>
Configuration for the labels used inside the sectors.
sectorLabel: AgPieSeriesSectorLabelOptions<DatumType>;

interface AgPieSeriesSectorLabelOptions<DatumType> {
  // Distance in pixels, used to make the label text closer to or further from the center. This offset is applied after positionRatio.
  // Default: `0` 
  positionOffset?: PixelSize;
  // Position of labels as a ratio proportional to pie radius (or doughnut thickness). Additional offset in pixels can be applied by using positionOffset.
  // Default: `0.5` 
  positionRatio?: Ratio;
  // A function that allows the modification of the label text based on input parameters. 
  formatter?: (params: AgPieSeriesLabelFormatterParams<DatumType>) => string;
  // Whether or not the labels should be shown. 
  enabled?: boolean;
  // The font style to use for the labels. 
  fontStyle?: FontStyle;
  // The font weight to use for the labels. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the labels. 
  fontSize?: FontSize;
  // The font family to use for the labels. 
  fontFamily?: FontFamily;
  // The colour to use for the labels. 
  color?: CssColor;
}

type PixelSize = number

type Ratio = number

interface AgPieSeriesLabelFormatterParams<DatumType> {
  // Datum from the series data array that the label is being rendered for. 
  datum: DatumType;
  // calloutLabelKey as specified on series options. 
  calloutLabelKey?: string;
  // calloutLabelValue as read from series data via the calloutLabelKey property. 
  calloutLabelValue?: string;
  // calloutLabelName as specified on series options. 
  calloutLabelName?: string;
  // sectorLabelKey as specified on series options. 
  sectorLabelKey?: string;
  // sectorLabelValue as read from series data via the sectorLabelKey property. 
  sectorLabelValue?: string;
  // sectorLabelName as specified on series options. 
  sectorLabelName?: string;
  // angleKey as specified on series options. 
  angleKey: string;
  // angleValue as read from series data via the angleKey property. 
  angleValue?: any;
  // angleName as specified on series options. 
  angleName?: string;
  // radiusKey as specified on series options. 
  radiusKey?: string;
  // radiusValue as read from series data via the radiusKey property. 
  radiusValue?: any;
  // radiusName as specified on series options. 
  radiusName?: string;
  // The ID of the series. 
  seriesId: string;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string
calloutLine
AgPieSeriesCalloutOptions
Configuration for the callout lines used with the labels for the sectors.
calloutLine: AgPieSeriesCalloutOptions;

interface AgPieSeriesCalloutOptions {
  // The colours to cycle through for the strokes of the callouts. 
  colors?: CssColor[];
  // The length in pixels of the callout lines. 
  length?: PixelSize;
  // The width in pixels of the stroke for callout lines. 
  strokeWidth?: PixelSize;
}

type CssColor = string

type PixelSize = number
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.
radiusKey
string
The key to use to retrieve radius values from the data.
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.
calloutLabelKey
string
The key to use to retrieve label values from the data.
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.
sectorLabelKey
string
The key to use to retrieve sector label values from the data.
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.
fills
CssColor[]
The colours to cycle through for the fills of the sectors.
Default: ['#f3622d', '#fba71b', '#57b757', '#41a9c9', '#4258c9', '#9a42c8', '#c84164', '#888888']
fills: CssColor[];

type CssColor = string
strokes
CssColor[]
The colours to cycle through for the strokes of the sectors.
Default: ['#aa4520', '#b07513', '#3d803d', '#2d768d', '#2e3e8d', '#6c2e8c', '#8c2d46', '#5f5f5f']
strokes: CssColor[];

type CssColor = string
fillOpacity
Opacity
The opacity of the fill for the sectors.
Default: 1
fillOpacity: Opacity;

type Opacity = number
strokeOpacity
Opacity
The opacity of the stroke for the sectors.
Default: 1
strokeOpacity: Opacity;

type Opacity = number
strokeWidth
PixelSize
The width in pixels of the stroke for the sectors.
Default: 1
strokeWidth: PixelSize;

type PixelSize = number
lineDash
PixelSize[]
Defines how the pie sector strokes are rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, [6, 3] means dashes with a length of 6 pixels with gaps between of 3 pixels.
lineDash: PixelSize[];

type PixelSize = number
lineDashOffset
PixelSize
The initial offset of the dashed line in pixels.
Default: 0
lineDashOffset: PixelSize;

type PixelSize = number
rotation
number
The rotation of the pie series in degrees.
Default: 0
outerRadiusOffset
PixelSize
The offset in pixels of the outer radius of the series. Used to construct doughnut charts.
Default: 0
outerRadiusOffset: PixelSize;

type PixelSize = number
outerRadiusRatio
Ratio
The ratio of the outer radius of the series. Used to adjust the outer radius proportionally to the automatically calculated value.
outerRadiusRatio: Ratio;

type Ratio = number
innerRadiusOffset
PixelSize
The offset in pixels of the inner radius of the series. Used to construct doughnut charts. If this is not provided, or innerRadiusRatio is unset, or a value of zero is given, a pie chart will be rendered.
Default: 0
innerRadiusOffset: PixelSize;

type PixelSize = number
innerRadiusRatio
Ratio
The ratio of the inner radius of the series. Used to construct doughnut charts. If this is not provided, or innerRadiusOffset is unset, or a value of zero or one is given, a pie chart will be rendered.
innerRadiusRatio: Ratio;

type Ratio = number
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.
shadow: AgDropShadowOptions;

interface AgDropShadowOptions {
  // Whether or not the shadow is visible. 
  enabled?: boolean;
  // The colour of the shadow. 
  color?: CssColor;
  // The horizontal offset in pixels for the shadow. 
  xOffset?: PixelSize;
  // The vertical offset in pixels for the shadow. 
  yOffset?: PixelSize;
  // The radius of the shadow's blur, given in pixels. 
  blur?: PixelSize;
}

type CssColor = string

type PixelSize = number
tooltip
AgPieSeriesTooltip
Series-specific tooltip configuration.
tooltip: AgPieSeriesTooltip;

interface AgPieSeriesTooltip {
  // Function used to create the content for tooltips. 
  renderer?: (params: AgPieSeriesTooltipRendererParams) => string | AgTooltipRendererResult;
  // Whether or not to show tooltips when the series are hovered over. 
  enabled?: boolean;
}

interface AgPieSeriesTooltipRendererParams {
  // calloutLabelKey as specified on series options. 
  calloutLabelKey?: string;
  // calloutLabelName as specified on series options. 
  calloutLabelName?: string;
  // sectorLabelKey as specified on series options. 
  sectorLabelKey?: string;
  // sectorLabelName as specified on series options. 
  sectorLabelName?: string;
  // angleKey as specified on series options. 
  angleKey: string;
  // angleValue as read from series data via the angleKey property. 
  angleValue?: any;
  // angleName as specified on series options. 
  angleName?: string;
  // radiusKey as specified on series options. 
  radiusKey?: string;
  // radiusValue as read from series data via the radiusKey property. 
  radiusValue?: any;
  // radiusName as specified on series options. 
  radiusName?: string;
  // Datum from the series data array that the tooltip is being rendered for. 
  datum: any;
  // Series title or yName depending on series configuration. 
  title?: string;
  // Series primary colour, as selected from the active theme, series options or formatter. 
  color?: CssColor;
  // The ID of the series. 
  seriesId: string;
}

type CssColor = string

interface AgTooltipRendererResult {
  // Title text for the tooltip header. 
  title?: string;
  // Content text for the tooltip body. 
  content?: string;
}
innerLabels
AgDoughnutInnerLabel[]
Configuration for the text lines to display inside the series, typically used when rendering a doughnut chart
innerLabels: AgDoughnutInnerLabel[];

interface AgDoughnutInnerLabel {
  // The text to show in the inner label. 
  text: string;
  // The font style to use for the inner label. 
  fontStyle?: FontStyle;
  // The font weight to use for the inner label. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the inner label. 
  fontSize?: FontSize;
  // The font family to use for the inner label. 
  fontFamily?: FontFamily;
  // The colour to use for the inner label. 
  color?: CssColor;
  // The margin in pixels before and after the inner label. 
  margin?: PixelSize;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

type CssColor = string

type PixelSize = number
innerCircle
AgDoughnutInnerCircle
Configuration for the area inside the series, only visible when rendering a doughnut chart by using innerRadiusOffset or innerRadiusRatio
innerCircle: AgDoughnutInnerCircle;

interface AgDoughnutInnerCircle {
  // The colour of the fill for the inner circle. 
  fill: CssColor;
  // The opacity of the fill for the inner circle. 
  fillOpacity?: Opacity;
}

type CssColor = string

type Opacity = number
formatter
Function
A formatter function for adjusting the styling of the pie sectors.
formatter = (
    params: AgPieSeriesFormatterParams<DatumType>
) => AgPieSeriesFormat;

interface AgPieSeriesFormatterParams<DatumType> {
  datum: DatumType;
  fill?: CssColor;
  stroke?: CssColor;
  strokeWidth: PixelSize;
  highlighted: boolean;
  angleKey: string;
  radiusKey?: string;
  sectorLabelKey?: string;
  seriesId: string;
}

type CssColor = string

type PixelSize = number

interface AgPieSeriesFormat {
  fill?: CssColor;
  fillOpacity?: Opacity;
  stroke?: CssColor;
  strokeWidth?: PixelSize;
}

type Opacity = number
listeners
AgSeriesListeners<DatumType>
A map of event names to event listeners.
listeners: AgSeriesListeners<DatumType>;

interface AgSeriesListeners<DatumType> {
  // The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked. 
  nodeClick: (params: AgSeriesNodeClickParams<DatumType>) => void;
}

interface AgSeriesNodeClickParams<DatumType> {
  // Event type. 
  type: 'nodeClick';
  // Series ID, as specified in series.id (or generated if not specified) 
  seriesId: string;
  // Datum from the series data array. 
  datum: DatumType;
  // xKey as specified on series options 
  xKey?: string;
  // yKey as specified on series options 
  yKey?: string;
  // sizeKey as specified on series options 
  sizeKey?: string;
  // labelKey as specified on series options 
  labelKey?: string;
  // colorKey as specified on series options 
  colorKey?: string;
  // angleKey as specified on series options 
  angleKey?: string;
  // calloutLabelKey as specified on series options 
  calloutLabelKey?: string;
  // sectorLabelKey as specified on series options 
  sectorLabelKey?: string;
  // radiusKey as specified on series options 
  radiusKey?: string;
}
id
string
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.
Default: auto-generated value
data
DatumType[]
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible
boolean
Whether or not to display the series.
showInLegend
boolean
Whether or not to include the series in the legend.
cursor
string
The cursor to use for hovered area markers. This config is identical to the CSS cursor property.
highlightStyle
AgSeriesHighlightStyle
Configuration for series markers and series line highlighting when a marker / data point or a legend item is hovered over.
highlightStyle: AgSeriesHighlightStyle;

interface AgSeriesHighlightStyle {
  // Highlight style used for an individual marker when tapped or hovered over. 
  item?: AgSeriesHighlightMarkerStyle;
  // Highlight style used for whole series when one of its markers is tapped or hovered over. 
  series?: AgSeriesHighlightSeriesStyle;
}

interface AgSeriesHighlightMarkerStyle {
  // The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  fill?: CssColor;
  // The opacity of the fill for the highlighted item. 
  fillOpacity?: Opacity;
  // The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  stroke?: CssColor;
  // The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}

type CssColor = string

type Opacity = number

type PixelSize = number

interface AgSeriesHighlightSeriesStyle {
  enabled?: boolean;
  // The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming. 
  dimOpacity?: Opacity;
  // The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight. 
  strokeWidth?: PixelSize;
}

Next Up

Continue to the next section to learn about treemap.