Pie Charts

Overview

ZingChart supports these pie chart types:

These chart types can then be modified to appear as:

  • Exploded
  • Semicircle Donut

Note: We also offer two pie chart module variations: the nested pie chart and the bubble pie chart.

Note: See our Pie Chart Gallery for inspiration on all the different pie chart possibilities.

Pie Chart Types

To specify the chart type, add a type attribute to the chart object and provide one of the following values: navpie, pie, pie3d, ring, or ring3d. This section also explains how to create small multiples and exploded pie charts.

Note: Learn more about how to create 3D charts with our 3D Charts Tutorial.

Pie Chart

Our standard pie chart is specified by the pie value. Without further modification, here is how the default pie chart appears:

{
  type: 'pie'
}
https://app.zingsoft.com/demos/embed/5FZ1FRAA
https://app.zingsoft.com/demos/embed/5FZ1FRAA

Nav Pie Chart

Our navpie pie chart groups pie slices that fall under a specified threshold into a single pie slice and turns that slice into a drilldown pie chart. To create one, first add a graphset array. Inside, add the type attribute with navpie as its value. Next, add an options object and use the threshold attribute to specify a threshold value. To style the back-button that appears after you drill down, use the back object.

}
  graphset: [
    {
      type: 'navpie',
      options: {
        threshold: '15%',
        others: {
          backgroundColor: '#999 #333'
        },
        slice: 0.65,
        back: {
          padding: 10,
          fontWeight: 'bold',
          color: '#fff',
          fontSize: 12,
          border: '3px solid #47a',
          borderRadius: 9,
          backgroundColor: '#369',
          shadow: true,
          shadowAlpha: 0.5
        }
      },
    }
  ]
}
https://app.zingsoft.com/demos/embed/MF0X2CAP
https://app.zingsoft.com/demos/embed/MF0X2CAP

Donut Chart

The donut chart (also known as a doughnut chart) is specified by the ring value. It’s a pie chart with a hole in the center (the donut ring or hole), which by default is sized to be 0.35, or 35% of the pie’s radius.

Note: You can modify the donut ring size. Create a plot object and insert a slice attribute. Specify your desired ring size as a percentage or pixel value.

{
  type: ring,
  title: {
    text: "Donut Chart"
  },
  plot: {
    //Use the "slice" attribute to adjust the size of the donut ring.
  },
https://app.zingsoft.com/demos/embed/JBLXGLX7
https://app.zingsoft.com/demos/embed/JBLXGLX7

Semicircle Donut Chart

The donut chart can also be modified into a semicircle donut chart (aka semicircle pie). Commonly used in dashboards, the main advantage of the semicircle donut chart is that it displays the same amount of data while only using half the space.

To create one, you'll need to add a scaleR object. Set refAngle and aperture to 180.

{
  type : 'ring',
  scaleR : {
    // Set to half ring
    refAngle : 180,
    aperture : 180
  },
}
https://app.zingsoft.com/demos/embed/CO4976FF
https://app.zingsoft.com/demos/embed/CO4976FF

Small Multiples

You can create small multiples (also known as a trellis chart) using our different pie chart types. While small multiples are generally created by using a layout attribute (to organize the columns and rows) and the graphset array (to contain the charts), there is a shortcut method that allows you to create multiple pie charts in a single chart object.

To create multiple pie charts, you need to:

  1. Add a scale object

  2. Use the layout attribute to specify how many columns and rows the pie charts should be organized into (e.g., 1x2 would equal one column with two rows and 2x3 would equal two columns with three rows).

When providing your data, each values array corresponds to a pie slice (or node). With multiple pie charts, assign your values in the following format:

series: [
  { values: [pie1Slice1, pie2Slice1, pie3Slice1, ..., pieNSlice1]},
  { values: [pie1Slice2, pie2Slice2, pie3Slice2, ..., pieNSlice2]},
  ...,
  { values: [pie1SliceN, pie2SliceN, pie3SliceN, ..., pieNSliceN]}
]

See the following chart. Note that in addition to the layout, you can modify the size of all of the charts by adding a size-factorattribute to the scale object and providing a decimal or percentage value.

{
  type: 'pie', //'pie', "pie3d", ring:", or ring:3d"
  title: {
    text: "Multiple Pie Charts"
  },
  scale: {
    layout: "2x3", //specify the layout by rows and columns
    'size-factor':0.5 //provide a decimal or percentage value
  },
  plot: {
    'value-box': {
      'font-size':10,
      'font-weight': "normal",
      placement: "out"
    }
  },
  series: [
    { values: [59,60,50,40,61,58]},
    { values: [55,40,40,55,35,57]},
    { values: [30,35,30,49,31,39]},
    { values: [28,30,20,40,28,36]},
    { values: [15,20,10,16,14,32]}
  ]
}
https://app.zingsoft.com/demos/embed/Y88TU2BD
https://app.zingsoft.com/demos/embed/Y88TU2BD

Exploded Pie Chart

You can create an exploded pie chart look (slices display as pulled away from the overall pie) using any of our pie chart types. In the plot and/or series object(s), add an offset-r attribute with a numeric or percentage value. Higher values will pull slices farther from the center of the overall pie.

Note: Exploded pie charts only displays slices pulled from the overall chart. To have slices detached from the overall chart, you'll use the detached attribute discussed further below in the Chart-Specific Properties section.

{
  type: "pie3d", //'pie', "pie3d", ring:", or ring:3d"
  plot: {
    'offset-r': "25%" //provide percentage or numeric value
  },

}
https://app.zingsoft.com/demos/embed/6QZH6SF6
https://app.zingsoft.com/demos/embed/6QZH6SF6

Data

Provide your pie chart data in the series array.

Pie Data

In the series array, assign a value to each values object. Each value corresponds to a slice in the pie.

series: [
  { values: [slice1]},
  { values: [slice2]},
  { values: [slice3]},
  ...,
  { values: [sliceN]}
]

Note: You can have ZingChart automatically order your pie slices from largest to smallest. Create a plot object and add a layoutattribute. Set the value to auto. (This attribute also sets the pie chart’s default reference angle to 12 o'clock, or zero degrees. For more information, see the Reference Angle section below.)

Small Multiples Data

When creating pie chart small multiples (or a trellis chart) via the pie chart-specific shortcut method, each values object will still correspond to a specific slice. However, the object will contain the values for that particular slice for all of the pie charts.

series: [
  { values: [pie1Slice1, pie2Slice1, pie3Slice1, ..., pieNSlice1]},
  { values: [pie1Slice2, pie2Slice2, pie3Slice2, ..., pieNSlice2]},
  { values: [pie1Slice3, pie2Slice3, pie3Slice3, ..., pieNSlice3]},
  ...,
  { values: [pie1SliceN, pie2SliceN, pie3SliceN, ..., pieNSliceN]}
]

Note: You must also specify the layout of your small multiples by creating a scale object and adding a layoutattribute. See the above Pie Chart Small Multiples section for more information.

Chart-Specific Properties

Once you've provided your pie chart type and data, you can configure the chart's elements such as offset, donut ring size, how pie slices are detached and/or clicked, and more.

Donut Ring Size

Use the slice attribute to create and/or modify the size of the donut ring. The attribute can be applied globally in the plot object or locally in the applicable series object. Provide the ring size as a percentage or pixel value.

{
  plot: {
    slice: "50%" //applied globally 
  },
  series: [
    {
      values: [59],
      slice: "80%" //applied locally 
    },
    { values: [55]},
    { values: [30]},
    { values: [28]},
    { values: [15]}
  ]
}
https://app.zingsoft.com/demos/embed/BFM946ER
https://app.zingsoft.com/demos/embed/BFM946ER

Detached Slices

Use the detached attribute to set whether or not the pie slice(s) is detached when the chart loads. The attribute can be applied globally in the plot object or locally in the series object. Clicking the detached slice will reattach it to the pie.

Note: This attribute differs from the offset-r attribute discussed in the Exploded Pie Chart section above, which does not reattach the slice to the pie.

{
  series: [
    {
      values: [59],
      'detached': true
    },
    { values: [55]},
    { values: [30]},
    { values: [28]},
    { values: [15]}
  ]
}
https://app.zingsoft.com/demos/embed/EYHI1VR9
https://app.zingsoft.com/demos/embed/EYHI1VR9

Clicked Slices

Use the detach attribute with a true or false value to specify whether or not the slice detaches from the pie when clicked on. The slices are set to detach by default. The attribute can be applied globally in the plot object or locally in the series object.

{
  type: "pie3d",
  plot: {
    'detach': false
  }
}
https://app.zingsoft.com/demos/embed/C0K07NOV
https://app.zingsoft.com/demos/embed/C0K07NOV

Further Customization

Further customize your pie chart by configuring your scales, styling your borders, backgrounds, and pie slice shapes, and incorporating value boxes, tooltips, and/or a legend.

Scale Configuration

Use the scale-r object to set the pie chart's aperture and reference angle. Use the scale object to set the size factor.

Note: For more information, refer to our scale and scale-r JSON Configuration pages.

Aperture

The pie chart is sized to 360 degrees (i.e., a circle) by default. You can change this by adding an aperture attribute to the scale-r object. Provide the desired aperture value (e.g., 180 is a half circle, 90 is a quarter circle, and so on).

{
  'scale-r': {
    aperture:300
  }
https://app.zingsoft.com/demos/embed/0OKITOAR
https://app.zingsoft.com/demos/embed/0OKITOAR

Reference Angle

The reference angle (or starting point) of our pie charts is set to 90 degrees (or 3 o'clock) by default. Add a ref-angleattribute to the scale-r object to change this. Provide the desired value, keeping in mind that the value is relative to the default starting angle. For example, providing a value of 270 would make the first pie slice appear at the 12 o'clock position. See the following chart:

{
  'scale-r': {
    'ref-angle':270 //relative to the starting 90 degree position.
  }
}
https://app.zingsoft.com/demos/embed/FT521R1M
https://app.zingsoft.com/demos/embed/FT521R1M

Alternatively, you can have the reference angle automatically set to zero and have the pie slices automatically sorted by size, from largest to smallest, by adding a layout': "auto attribute to the plot object. See the following chart:

{
  plot: {
    layout: "auto" //to order pie slices by size and have reference angle start at zero.
  }
}
https://app.zingsoft.com/demos/embed/EKDPP6J5
https://app.zingsoft.com/demos/embed/EKDPP6J5

Size Factor

The size of the pie chart can be modified by adding a size-factor attribute to the scale object. Provide a decimal or percentage value, and note that you can provide values greater or less than 1.0 or 100%.

{
  scale: {
    'size-factor':0.2
  },
}

See following chart for a comparison of 'size-factor':0.2 with 'size-factor':1.01:

https://app.zingsoft.com/demos/embed/DB94H8XS
https://app.zingsoft.com/demos/embed/DB94H8XS

Plot/Series Styling

You can style the backgrounds and borders of the pie slices using the background-color, border-width, border-color, line-style, alpha, and other styling attributes. Attributes can be applied globally in the plot object or locally in the series object.

Note: Refer to the Plot/Series Styling Tutorial and the Plot/Series JSON page for more information and a full attribute list.

{
  plot: {
    'border-width': 1,
    'border-color': "#cccccc",
    'line-style': "dotted",
  },
  series: [
    {
      values: [234],
      'background-color': "#cc0000"
    },
    {
      values: [121],
      'background-color': "#ff3300"
    }
  ]
}
https://app.zingsoft.com/demos/embed/UNU4950E
https://app.zingsoft.com/demos/embed/UNU4950E

Pie Transform

Use the pieTransform attribute to transform the shape of your pie chart slices. Available transforms are: none (default), bite, callout,flat, fold, flow, and droplet. bite, callout, flow, and fold accept numeric or percentage values.

{
  plot: {
    pieTransform: 'fold=20' // 'bite=20' | 'callout=20' | 'flow=20' | 'fold=20' | 'droplet' | 'flat'
  }
}

The following demo illustrates the different options available for styling your pie chart slices:

https://app.zingsoft.com/demos/embed/5JZ0P17M
https://app.zingsoft.com/demos/embed/5JZ0P17M

Tokens

Tokens (or string interpolation) are highly useful when customizing pie chart tooltips and value boxes. Commonly used pie chart tokens include:

TokenDescription
%data-_____Format for custom tokens. The custom token is defined in the plot or series object as an attribute or array using the "data" prefix (e.g., data-year). It is then recalled in the tooltips or value boxes (e.g., %data-year).
%node-percent-value %npvThe percentage value of the pie slice (node) relative to the entire pie (sum of all nodes) Demo
%node-value %vThe pie slice (node) value
%pie-total-valueThe sum of all the pie slice (node) values Demo
%plot-descriptionThe description of the current plot, pulled from the description attribute in the plot/series object
%plot-text %tThe text of the current plot, pulled from the text attribute in the plot/series object

Note: Refer to the Tokens Tutorial for a full list of available tokens.

Tooltips

Enable and style tooltips with a tooltip object in the plot object. Customize the tooltip's text with a text attribute and then provide your desired combination of text and tokens inside a string.

Note: Refer to the Tooltips Tutorial and Tooltips JSON page for more information and a full attribute list.

{
  plot: {
    tooltip: {
      text: "%t: %v (%npv%)",
      'font-color': "black",
      'font-family': "Georgia",
      'text-alpha':1,
      'background-color': "white",
      alpha:0.7,
      'border-width': 1,
      'border-color': "#cccccc",
      'line-style': "dotted",
      'border-radius': "10px",
      padding: "10%",
      placement: "node:out" //"node:out" or "node:center"
    },
}
https://app.zingsoft.com/demos/embed/U0TWAGTG
https://app.zingsoft.com/demos/embed/U0TWAGTG

Value Boxes

To enable and style value boxes, create a value-box object in the plot object. You can then customize the text, placement (in, out, center), and styling. You can also incorporate rules for when value boxes appear.

Note: Refer to the Value Boxes Tutorial and the Value Boxes JSON page for more information and a full attribute list.


In the following chart, rules were used to place value boxes in or out of the chart based on their value.

Note: Value boxes placed outside the pie slices are automatically drawn with connecting lines. To remove them, add a connected attribute and set the value to false.

{
  plot: {
    'value-box': {
      text: "%v",
      'font-size':12,
      'font-family': "Georgia",
      'font-weight': "normal",
      rules: [
        {
          rule: "%v > 50",
          placement: "in",
          'offset-r': "50%",
          'font-color': "white",
        },
        {
          rule: "%v <= 50",
          placement: "out",
          'font-color': "gray",
        }
      ]
    }
}
https://app.zingsoft.com/demos/embed/F6BBV6JX
https://app.zingsoft.com/demos/embed/F6BBV6JX

Alternatively, you can center the value box text, which is a useful option on donut charts.

Note: When the placement is set to center, the value boxes all collect in the middle of the chart, overlapping each other. To stop this, specify how you want the value box text formatted and styled. Next, use rules to turn off the visibility of all but the first value box.

{
  type: "ring",
  plot: {
    'value-box': {
      text: "%pie-total-value",
      placement: "center",
      'font-color': "black",
      'font-size':35,
      'font-family': "Georgia",
      'font-weight': "normal",
      rules: [
        {
          rule: "%p != 0",
          visible: false
        }
      ]
    },
  }
}
https://app.zingsoft.com/demos/embed/HLT1AZGT
https://app.zingsoft.com/demos/embed/HLT1AZGT

Legend

Enable and style a legend by creating a legend object in your chart object.

Note: Refer to the Legend Tutorial and the Legend JSON page for detailed instructions and a full attribute list.

{
  legend: {
    x: "75%",
    y: "25%",
    'border-width': 1,
    'border-color': "gray",
    'border-radius': "5px",
    header: {
      text: "Legend",
      'font-family': "Georgia",
      'font-size':12,
      'font-color': "#3333cc",
      'font-weight': "normal"
    },
    marker: {
      type: "circle"
    },
    'toggle-action': "remove",
    'minimize': true,
    'icon': {
      'line-color': "#9999ff"
    },
    'max-items':8,
    'overflow': "scroll"
  }
}
https://app.zingsoft.com/demos/embed/SX05IDLH
https://app.zingsoft.com/demos/embed/SX05IDLH

Interactive Charts

ZingChart supports interactive pie chart features such as animation, shared legends, drilldown, and more.

Animation

You can create animated pie charts by adding an animation object to the plot object.

Note: Learn more about adding animation to your chart with our Animation Tutorial.

{
  "plot": {
    "animation": {
      "on-legend-toggle": true, //set to true to show animation and false to turn off
      "effect": 5,
      "method": 1,
      "sequence": 1,
      "speed": 1
    }
  }
}
https://app.zingsoft.com/demos/embed/GT3FGNEJ
https://app.zingsoft.com/demos/embed/GT3FGNEJ

Shared Legend

When working with pie chart small multiples, you can create a shared legend that allows users to interact with all charts simultaneously. In the legend object, add a shared attribute with a true value.

Note: Learn more about shared legends with our Shared Interactions Tutorial.

{
  "legend": {
    "shared": true
  },
}
https://app.zingsoft.com/demos/embed/8V97MY98
https://app.zingsoft.com/demos/embed/8V97MY98

Drilldown

You can create drilldown charts using chart types such as pie and bar.

Note: Learn more about drilldown features with our Drilldown Tutorial.

https://app.zingsoft.com/demos/embed/8ZAZD024
https://app.zingsoft.com/demos/embed/8ZAZD024

Summary

Have questions about how pie charts work? We're happy to help! Email support@zingchart.com or start a chat right here on this page for support.