Blog Help & Support Contact About Login

 Show Nav

JavaScript Pie Charts

Overview

JavaScript pie charts or graphs display data as proportional slices of a circular pie. There are many different pie chart variations, and ZingChart supports standard pie, 3D pie, donut, 3D donut, exploded pie, pie chart small multiples, and more. You can create interactive pie charts by incorporating features such as animation, legends, and drilldown. Browse our ZingChart Gallery for inspiration and ideas.

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

Pie Chart Types

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

Pie Chart

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

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"Pie Chart"
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

3D Pie Chart

Our three-dimensional pie chart is specified by the "pie3d" value. Read the 3D Charts Tutorial for information on how to modify 3D charts. You can use the "3d-aspect" object to display your pie chart in a true 3D (default) or isometric view. You can also adjust the chart’s angle, depth, and zoom.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie3d",
  "title":{
    "text":"3D Pie Chart"
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"ring",
  "title":{
    "text":"Donut Chart"
  },
  "plot":{
    //Use the "slice" attribute to adjust the size of the donut ring.
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

3D Donut Chart

The three-dimensional donut chart is specified by the "ring3d" value. With this chart type, you can use a "3d-aspect" object to display the chart in a true 3D (default) or isometric view. You can also adjust the chart’s angle, depth, and zoom. See the 3D Charts Tutorial for more information.

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"ring3d",
  "title":{
    "text":"3D Donut Chart"
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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:

  • Create a "scale" object and add a "layout" attribute.
  • Provide data for all of the charts.

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

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":[pie1-slice1, pie2-slice1, pie3-slice1, ..., pieN-slice1]},
  {"values":[pie1-slice2, pie2-slice2, pie3-slice2, ..., pieN-slice2]},
  {"values":[pie1-slice3, pie2-slice3, pie3-slice3, ..., pieN-slice3]},
  ...,
  {"values":[pie1-sliceN, pie2-sliceN, pie3-sliceN, ..., pieN-sliceN]}
]

See the below chart. Note that in addition to the layout, you can modify the size of all of the charts. Add a "size-factor" attribute to the "scale" object, and provide a decimal or percentage value.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie", //"pie", "pie3d", "ring", or "ring3d"
  "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]}
  ]
}

Exploded Pie Chart

You can created exploded pie charts using any of our pie chart types. Use the "offset-r" attribute in the "plot" and/or "series" object(s) to pull out one or more slices from the overall pie.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie3d", //"pie", "pie3d", "ring", or "ring3d"
  "title":{
    "text":"Exploded Pie Chart"
  },
  "plot":{
    "offset-r":"25%" //provide percentage value
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

Series 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 that you can have ZingChart automatically order your pie slices, from largest to smallest. Create a "plot" object and add a "layout"attribute. 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":[pie1-slice1, pie2-slice1, pie3-slice1, ..., pieN-slice1]},
  {"values":[pie1-slice2, pie2-slice2, pie3-slice2, ..., pieN-slice2]},
  {"values":[pie1-slice3, pie2-slice3, pie3-slice3, ..., pieN-slice3]},
  ...,
  {"values":[pie1-sliceN, pie2-sliceN, pie3-sliceN, ..., pieN-sliceN]}
]

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

Basic Elements

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

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.

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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"'aperture' attribute"
  },
  "scale-r":{
    "aperture":300
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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-angle" attribute 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. E.g., providing a value of 270 would make the first pie slice appear at the 12 o'clock position. See the below chart.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"'ref-angle' attribute"
  },
  "scale-r":{
    "ref-angle":270 //relative to the starting 90 degree position.
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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 below chart.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"'layout' attribute in 'plot' object"
  },
  "plot":{
    "layout":"auto" //to order pie slices by size and have reference angle start at zero.
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[130]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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%. See the below chart.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "graphset":[
    {
      "type":"pie",
      "title":{
        "text":"'size-factor'<br>attribute"
      },
      "scale":{
        "size-factor":0.2
      },
      "height":"100%",
      "width":"40%",
      "x":"0%",
      "y":"0%",
      "plot":{
        "value-box":{ 
          "placement":"out",
          "font-family":"Georgia",
          "font-size":10,
          "font-weight":"normal"
        }
      },
      "series":[
        {"values":[59]},
        {"values":[55]},
        {"values":[30]},
        {"values":[28]},
        {"values":[15]}
      ]
    },
    {
      "type":"pie",
      "scale":{
        "size-factor":1.01
      },
      "height":"100%",
      "width":"60%",
      "x":"40%",
      "y":"0%",
      "plot":{
        "value-box":{ 
          "font-family":"Georgia",
          "font-size":14,
          "font-weight":"normal",
          "offset-r":"35%"
        }
      },
      "series":[
        {"values":[59]},
        {"values":[55]},
        {"values":[30]},
        {"values":[28]},
        {"values":[15]}
      ]
    }
  ]
}

Chart-Specific

Pie chart-specific customizations include modifying the size of the donut ring, allowing for the reattachment of detached pie slices, setting up offset pie slices, and disabling the detachment of clicked pie slices.

Donut Ring Size

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

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie3d",
  "title":{
    "text":"'slice' attribute"
  },
  "plot":{
    "slice":"50%"
  },
  "series":[
    {
      "values":[59],
      "slice":"80%"
    },
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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 ("plot" object) or locally ("series" object). Clicking the detached slice will reattach it to the pie.

Note: This attribute differs from the "offset-r" attribute discussed in the next section, which does not reattach the slice to the pie.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie3d",
  "title":{
    "text":"'detached' attribute"
  },
  "series":[
    {
      "values":[59],
      "detached":true
    },
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

Offset Slices

Use the "offset-r" attribute to pull out one or more slices from the rest of the pie. Often referred to as an exploded pie chart, the attribute can be applied globally ("plot" object) or locally ("series" object). Provide the pie slice offset as a percentage or pixel value.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"ring3d",
  "title":{
    "text":"'offset-r' attribute"
  },
  "plot":{
    "offset-r":"10%"
  },
  "series":[
    {
      "values":[59],
      "offset-r":"35%"
    },
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

Clicked Slices

Use the "detach" attribute 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 ("plot" object) or locally ("series" object).

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie3d",
  "title":{
    "text":"'detach' attribute"
  },
  "plot":{
    "detach":false
  },
  "series":[
    {"values":[59]},
    {"values":[55]},
    {"values":[30]},
    {"values":[28]},
    {"values":[15]}
  ]
}

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. Refer to the Plot/Series Styling Tutorial and the Plot/Series JSON page for further information and a full attribute list.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"Pie Chart Styling"
  },
  "plot":{
    "border-width":1,
    "border-color":"#cccccc",
    "line-style":"dotted",
    "value-box":{
      "font-size":10,
      "font-weight":"normal",
      "placement":"out"
    }
  },
  "series":[
    {
      "values":[234],
      "background-color":"#cc0000"
    },
    {
      "values":[121],
      "background-color":"#ff3300"
    },
    {
      "values":[77],
      "background-color":"#ff6600"
    },
    {
      "values":[65],
      "background-color":"#ff9933"
    },
    {
      "values":[59],
      "background-color":"#ffcc00"
    },
    {
      "values":[35],
      "background-color":"#ace600"
    },
    {
      "values":[34],
      "background-color":"#88cc00"
    },
    {
      "values":[31],
      "background-color":"#339933"
    },
    {
      "values":[16],
      "background-color":"#66ccff"
    },
    {
      "values":[14],
      "background-color":"#3399ff"
    },
    {
      "values":[13],
      "background-color":"#0066ff"
    },
    {
      "values":[12],
      "background-color":"#3333cc"
    },
    {
      "values":[11],
      "background-color":"#6600ff"
    },
    {
      "values":[10],
      "background-color":"#9933ff"
    },
    {
      "values":[9],
      "background-color":"#9999ff"
    }
  ]
}

Tokens

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

Token Description
%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
%npv
The percentage value of the pie slice (node) relative to the entire pie (sum of all nodes).
%node-value
%v
The pie slice (node) value.
%pie-total-value The sum of all the pie slice (node) values.
%plot-description The description of the current plot, pulled from the "description" attribute in the plot/series object.
%plot-text
%t
The text of the current plot, pulled from the "text" attribute in the plot/series object.

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

Tooltips

Tooltips appear when you hover over the pie slices. Create a "tooltip" object in the "plot" object to customize the text and styling. Refer to the Tooltips Tutorial and Tooltips JSON page for more information and a full attribute list.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"Tooltips"
  },
  "subtitle":{
    "text":"Hover over the pie slices",
    "font-weight":"normal"
  },
  "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"
    },
    ...omitted for brevity...
  },
  "plotarea":{
    "margin-top":"12%"
  },
  "series":[
    ...omitted for brevity...
  ]
}

Value Boxes

Value boxes are fixed labels that appear adjacent to the pie slices. Create a "value-box" object in the "plot" object to customize the "text", "placement" ("in", "out", "center"), and styling. You can also incorporate rules. Refer to the Value Boxes Tutorial and the Value Boxes JSON page for more information and a full attribute list.

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

Tip: 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.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"Value Boxes"
  },
  "subtitle":{
    "text":"with placement set to 'in' and 'out' based on the node value",
    "font-weight":"normal"
  },
  "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",
        }
      ]
    },
    ...omitted for brevity...
  },
  "plotarea":{
    "margin-top":"12%"
  },
  "series":[
    ...omitted for brevity...
  ]
}

Alternatively, you can center the value box text. This is an especially useful option on donut charts. Note that 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. See the below chart.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"ring",
  "title":{
    "text":"Value Boxes"
  },
  "subtitle":{
    "text":"with placement set to 'center' to show the total pie value",
    "font-weight":"normal"
  },
  "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
        }
      ]
    },
    ...omitted for brevity...
  },
  "plotarea":{
    "margin-top":"12%"
  },
  "series":[
    ...omitted for brevity...
  ]
}

Legend

Adding a legend can help users better understand your pie chart, and our library supports many interactive legend features. Create a "legend" object. Refer to the Legend Tutorial and the Legend JSON page for detailed instructions and a full attribute list.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

{
  "type":"pie",
  "title":{
    "text":"Legend"
  },
  "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"
  },
  "plotarea":{
    "margin-right":"30%",
    "margin-top":"15%"
  },
  "plot":{
    ...omitted for brevity...
  },
  "series":[
    ...omitted for brevity...
  ]
}

Interactive Charts

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

Animation

You can create animated pie charts using the "animation" object. Refer to the Animation Tutorial for more information.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Shared Legend

When working with pie chart small multiples, you can create a shared legend that allows users to interact with all charts simultaneously. Refer to the Shared Interactions Tutorial for more information.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Drilldown

You can create drilldown charts using chart types such as pie and bar. Refer to the Drilldown Tutorial for more information.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Summary

Got a question about how pie charts work? We are happy to help. Email support@zingchart.com or start a chat right here on this page for help.