Anatomy of a Pie Chart

In the course of this tutorial, we’ll explain how, and build an actual working Pie chart.

Creating a Pie chart

Before we can do anything, we need to create a Pie chart object, which in this case an instance of a PieChart class.

A Pie chart, at the very least needs the following things:

1. Chart instance;
2. Data;
3. At least one Series.

This tutorial will walk through all of these.

Importing modules/scripts

Needless to say, before you can do anything, you need to make sure all required modules (in TypeScript), or files (in JavaScript) are imported. Please refer to our Getting started articles for more details:

• Module loading instructions for TypeScript or ES6
• Script loading instructions for JavaScript

For a Pie chart, we’ll need to import core (main module) and charts modules.

TypeScript

import * as am4core from "@amcharts/amcharts4/core";
import * as am4charts from "@amcharts/amcharts4/charts";

JavaScript

<script src="//cdn.amcharts.com/lib/4/core.js"></script>
<script src="//cdn.amcharts.com/lib/4/charts.js"></script>

We’ll be importing and referring these as am4core and am4charts in the course of this article, and overally in our demos and tutorials.

Creating chart instance

For that we’re going to be using am4core.create() function. (or am4core.createFromConfig() if you are using JSON-based config approach)

TypeScript

let chart = am4core.create("chartdiv", am4charts.PieChart);

JavaScript

var chart = am4core.create("chartdiv", am4charts.PieChart);

JSON

var chart = am4core.createFromConfig({
  // ... chart config
}, "chartdiv", am4charts.PieChart);

Note

There’s a special comment on JSON-based setup down this article. Read on.

Data

Just like for most chart types, the data for a Pie chart is an array of objects. Each of those objects will represent a Slice and must at least contain one numeric value (Slice value) and a category (Slice title).

In-line data

We assign the data to the data to chart’s data property:

TypeScript

chart.data = [{
  "country": "Lithuania",
  "litres": 501.9
}, {
  "country": "Czech Republic",
  "litres": 301.9
}, {
  "country": "Ireland",
  "litres": 201.1
}, {
  "country": "Germany",
  "litres": 165.8
}, {
  "country": "Australia",
  "litres": 139.9
}, {
  "country": "Austria",
  "litres": 128.3
}, {
  "country": "UK",
  "litres": 99
}, {
  "country": "Belgium",
  "litres": 60
}, {
  "country": "The Netherlands",
  "litres": 50
}];

JavaScript

chart.data = [{
  "country": "Lithuania",
  "litres": 501.9
}, {
  "country": "Czech Republic",
  "litres": 301.9
}, {
  "country": "Ireland",
  "litres": 201.1
}, {
  "country": "Germany",
  "litres": 165.8
}, {
  "country": "Australia",
  "litres": 139.9
}, {
  "country": "Austria",
  "litres": 128.3
}, {
  "country": "UK",
  "litres": 99
}, {
  "country": "Belgium",
  "litres": 60
}, {
  "country": "The Netherlands",
  "litres": 50
}];

JSON

{
  // ...
  "data": [{
    "country": "Lithuania",
    "litres": 501.9
  }, {
    "country": "Czech Republic",
    "litres": 301.9
  }, {
    "country": "Ireland",
    "litres": 201.1
  }, {
    "country": "Germany",
    "litres": 165.8
  }, {
    "country": "Australia",
    "litres": 139.9
  }, {
    "country": "Austria",
    "litres": 128.3
  }, {
    "country": "UK",
    "litres": 99
  }, {
    "country": "Belgium",
    "litres": 60
  }, {
    "country": "The Netherlands",
    "litres": 50
  }]
}

External data

We can also make the chart load external data using dataSource.

TypeScript

chart.dataSource.url = "pie_chart_data.json";

JavaScript

chart.dataSource.url = "pie_chart_data.json";

JSON

{
  // ...
  "dataSource": {
    "url": "pie_chart_data.json"
  }
}

Please refer to our “External data” article, for more details.

Slice series

In amCharts 4 universe, Pie chart is a serial chart.

Creating a series

A series of Slices is represented by an instance of PieSeries class.

In most serial charts, Pie chart included, all Series are included in a List accessible via chart’s series property.

To create a new Series, we just going to create a new instance of `PieSeries` and push it into `chart.series`:

TypeScript

let pieSeries = chart.series.push(new am4charts.PieSeries());

JavaScript

var pieSeries = chart.series.push(new am4charts.PieSeries());

JSON

{
  // ...
  "series": [{
    "type": "PieSeries",
    // Series settings
  }]
}

Setting up series

Now that we have a Series, we need to set it up.

At the very least, we need to specify the fields in data, this Series will get its values from. (remember a PieSeries needs a numeric value and a string title/category for each Slice)

That’s where Series property dataFields comes into play:

TypeScript

pieSeries.dataFields.value = "litres";
pieSeries.dataFields.category = "country";

JavaScript

pieSeries.dataFields.value = "litres";
pieSeries.dataFields.category = "country";

JSON

{
  // ...
  "series": [{
    "type": "PieSeries",
    "dataFields": {
      "value": "litres",
      "category": "country"
    }
  }]
}

As you can see, Slice’s numeric value is represented by a data field “value”, while string title with a “category”.

Note

Check out dedicated “Series” article has more information about concepts of Series.

Putting it all together

Now that we have all the required elements, let’s put it all together:

TypeScript

// Import modules
import * as am4core from "@amcharts/amcharts4/core";
import * as am4charts from "@amcharts/amcharts4/charts";

// Create chart instance
let chart = am4core.create("chartdiv", am4charts.PieChart);

// Add data
chart.data = [{
  "country": "Lithuania",
  "litres": 501.9
}, {
  "country": "Czech Republic",
  "litres": 301.9
}, {
  "country": "Ireland",
  "litres": 201.1
}, {
  "country": "Germany",
  "litres": 165.8
}, {
  "country": "Australia",
  "litres": 139.9
}, {
  "country": "Austria",
  "litres": 128.3
}, {
  "country": "UK",
  "litres": 99
}, {
  "country": "Belgium",
  "litres": 60
}, {
  "country": "The Netherlands",
  "litres": 50
}];

// Add and configure Series
let pieSeries = chart.series.push(new am4charts.PieSeries());
pieSeries.dataFields.value = "litres";
pieSeries.dataFields.category = "country";

JavaScript

<script src="//cdn.amcharts.com/lib/4/core.js"></script>
<script src="//cdn.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 100%; height: 400px;"></div>

<script>
// Create chart instance
var chart = am4core.create("chartdiv", am4charts.PieChart);

// Add data
chart.data = [{
  "country": "Lithuania",
  "litres": 501.9
}, {
  "country": "Czech Republic",
  "litres": 301.9
}, {
  "country": "Ireland",
  "litres": 201.1
}, {
  "country": "Germany",
  "litres": 165.8
}, {
  "country": "Australia",
  "litres": 139.9
}, {
  "country": "Austria",
  "litres": 128.3
}, {
  "country": "UK",
  "litres": 99
}, {
  "country": "Belgium",
  "litres": 60
}, {
  "country": "The Netherlands",
  "litres": 50
}];

// Add and configure Series
var pieSeries = chart.series.push(new am4charts.PieSeries());
pieSeries.dataFields.value = "litres";
pieSeries.dataFields.category = "country";
</script>

JSON

<script src="//cdn.amcharts.com/lib/4/core.js"></script>
<script src="//cdn.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 100%; height: 400px;"></div>

<script>
// Create chart instance
var chart = am4core.createFromConfig({

  // Add data
  "data": [{
    "country": "Lithuania",
    "litres": 501.9
  }, {
    "country": "Czech Republic",
    "litres": 301.9
  }, {
    "country": "Ireland",
    "litres": 201.1
  }, {
    "country": "Germany",
    "litres": 165.8
  }, {
    "country": "Australia",
    "litres": 139.9
  }, {
    "country": "Austria",
    "litres": 128.3
  }, {
    "country": "UK",
    "litres": 99
  }, {
    "country": "Belgium",
    "litres": 60
  }, {
    "country": "The Netherlands",
    "litres": 50
  }],

  // Create and configure Series
  "series": [{
    "type": "PieSeries",
    "dataFields": {
      "value": "litres",
      "category": "country"
    }
  }]
}, "chartdiv", am4charts.PieChart);
</script>

Here’s a live version of the chart we’ve just created: (implemented in JavaScript)

Open in CodePen

Taking it further

Configuring appearance

There are so much more settings we can apply to chart, Series and the slices.

For example, we can make Pie chart into a Donut chart by setting chart’s innerRadius property:

TypeScript

chart.innerRadius = am4core.percent(40);

JavaScript

chart.innerRadius = am4core.percent(40);

JSON

{
  // ...
  "innerRadius": "40%"
}

While we’re at it, let’s make each slice have white outline borders. To do that, we’ll need to access PieSeries’ slices property, or more precisely its template property.

PieSerie’s slices.template holds a dummy object of the Slice class, which will be used as a template (hence the name) when creating actual Slices. It has all the same properties as the Slice class (because it is an instance of the Slice class, duh). Anything you set on a template will make it onto actual slices.

OK, so let’s add a dark border around each slice to make them more prominent:

TypeScript

pieSeries.slices.template.stroke = am4core.color("#4a2abb");
pieSeries.slices.template.strokeWidth = 2;
pieSeries.slices.template.strokeOpacity = 1;

JavaScript

pieSeries.slices.template.stroke = am4core.color("#4a2abb");
pieSeries.slices.template.strokeWidth = 2;
pieSeries.slices.template.strokeOpacity = 1;

JSON

{
  // ...
  "series": [{
    "type": "PieSeries",
    "dataFields": {
      "value": "litres",
      "category": "country"
    },
    "slices": {
      "stroke": "#4a2abb",
      "strokeWidth": 2,
      "strokeOpacity": 1
    }
  }]
}

And voilà!

Open in CodePen

Biding slice appearance to data

You can also bind virtually any property of the slice to a field in data using what we call “property fields”.

Read more about property fields, or if you’re short on time, property fields is basically an object defining which property (key) should draw its value in data.

Suppose we have a “color” key in our data:

[{
  "country": "Lithuania",
  "litres": 501,
  "color": am4core.color("#ED1C24")
}, {
  "country": "Czechia",
  "litres": 301,
  "color": am4core.color("#235789")
}, {
  "country": "Ireland",
  "litres": 201,
  "color": am4core.color("#F1D302")
}, {
  "country": "Germany",
  "litres": 165,
  "color": am4core.color("#020100")
}]

Now we can use propertyFields of the slice template to bind its fill property a “color” field in data:

TypeScript

pieSeries.slices.template.propertyFields.fill = "color";

JavaScript

pieSeries.slices.template.propertyFields.fill = "color";

JSON

{
  // ...
  "series": [{
    "type": "PieSeries",
    // ...
    "slices": {
      "propertyFields": {
        "fill": "color"
      }
    }
  }]
}

Let’s see how this looks on a live chart:

Open in CodePen

Disabling various elements

It’s possible to disable various elements like ticks, labels and rollover tooltips.

To disable the former, use templates of the respectively named ticks and labels list templates:

TypeScript

pieSeries.labels.template.disabled = true;
pieSeries.ticks.template.disabled = true;

JavaScript

pieSeries.labels.template.disabled = true;
pieSeries.ticks.template.disabled = true;

JSON

{
  // ...
  "series": {
    // ...
    "ticks": {
      "disabled": true
    },
    "labels": {
      "disabled": true
    }
  }
}

Note

You can use those same templates to also configure labels and ticks, like for example set fill to change color.

To disable the tooltip which appears on slice hover, simply reset tooltipText on its template:

TypeScript

pieSeries.slices.template.tooltipText = "";

JavaScript

pieSeries.slices.template.tooltipText = "";

JSON

{
  // ...
  "series": {
    // ...
    "slices": {
      "tooltipText": ""
    }
  }
}

Here’s a working example with all of the above:

Open in CodePen

Controlling appearance via states

In short, states is a powerful amCharts 4 concept allowing application of property values to elements when certain actions happen.

Like, for example, an element is hovered.

Pie series’ slices has already three states pre-created for us:

1. "default" state, which is applied when slice is in its initial position.
2. "hover" state, which is applied when you hover or touch the slice.
3. "active" state, which is applied when you click or tap the slice so it pulls out.

Each of those states, apply values to certain slice properties to modify its appearance.

For example, "hover" state, when applied, sets slice’s scale to 1.1 making it grow slightly.

When you click a slice and "active" state is applied, it sets slice’s shiftRadius property, which makes slice look pulled out.

To modify how slices behave in each of those scenarios, you need to modify the respective states’ properties values.

For example, if we don’t want the slice to grow on hover, we’d do this:

TypeScript

let hs = pieSeries.slices.template.states.getKey("hover");
hs.properties.scale = 1;

JavaScript

var hs = pieSeries.slices.template.states.getKey("hover");
hs.properties.scale = 1;

JSON

{
  // ...
  "series": {
    // ...
    "slices": {
      "states": {
        "hover": {
          "properties": {
            "scale": 1
          }
        }
      }
    }
  }
}

Similarly, if we don’t want slice to pull out on click, we’d need to modify "active" state:

TypeScript

let as = pieSeries.slices.template.states.getKey("active");
as.properties.shiftRadius = 0;

JavaScript

var as = pieSeries.slices.template.states.getKey("active");
as.properties.shiftRadius = 0;

JSON

{
  // ...
  "series": {
    // ...
    "slices": {
      "states": {
        "active": {
          "properties": {
            "shiftRadius": 1
          }
        }
      }
    }
  }
}

We can also, modify any of the slices’ properties that way just as well.

For example, if we want to disable growing on hover, but would rather modify fill opacity of the slice, we can do this:

TypeScript

pieSeries.slices.template.fillOpacity = 1;

let hs = pieSeries.slices.template.states.getKey("hover");
hs.properties.scale = 1;
hs.properties.fillOpacity = 0.5;

JavaScript

pieSeries.slices.template.fillOpacity = 1;

var hs = pieSeries.slices.template.states.getKey("hover");
hs.properties.scale = 1;
hs.properties.fillOpacity = 0.5;

JSON

{
  // ...
  "series": {
    // ...
    "slices": {
      "fillOpacity": 1,
      "states": {
        "hover": {
          "properties": {
            "scale": 1,
            "fillOpacity": 0.5
          }
        }
      }
    }
  }
}

Important

Notice, how we set fillOpacity on slice template as well. This is required, so that slice knows that it needs to return to this particular fill opacity when is no longer hovered.

Open in CodePen

More info

For more information about states read our dedicated “States” article.

One more thing before you go. There’s also a specially-named theme: "hoverActive". It is not created by default, so you would need to create it. If created, it will be applied in those situations when an “active” slice is hovered.

Adding a legend

Even if it’s not required, adding a legend might improve user experience. It can provide visual reference for the user, as well as allow toggling certain Slices.

To add a legend, we simply create an instance of Legend class and assign it to chart’s legend property. It’s as simple as that.

TypeScript

chart.legend = new am4charts.Legend();

JavaScript

chart.legend = new am4charts.Legend();

JSON

{
  // ...
  "legend": {
    "type": "Legend"
  }
}

Note

Refer to the “Legend” article for more details.

Setting themes

amCharts 4 makes it easy to apply themes to am4charts. Let’s make our chart more lively by enabling “Animated” theme.

To do so, we’ll need to remember to import the theme itself as well as set the system to use it.

TypeScript

// Import modules
import * as am4core from "@amcharts/amcharts4/core";
import * as am4charts from "@amcharts/amcharts4/charts";
import am4themes_animated from "@amcharts/amcharts4/themes/animated";

// Set theme
am4core.useTheme(am4themes_animated);

// Create chart instance
let chart = am4core.create("chartdiv", am4charts.PieChart);

// ...

JavaScript

<script src="//cdn.amcharts.com/lib/4/core.js"></script>
<script src="//cdn.amcharts.com/lib/4/charts.js"></script>
<script src="//cdn.amcharts.com/lib/4/themes/animated.js"></script>

<div id="chartdiv" style="width: 100%; height: 400px;"></div>

<script>
// Set theme
am4core.useTheme(am4themes_animated);

// Create chart instance
var chart = am4core.create("chartdiv", am4charts.PieChart);

// ...
</script>

JSON

<script src="//cdn.amcharts.com/lib/4/core.js"></script>
<script src="//cdn.amcharts.com/lib/4/charts.js"></script>
<script src="//cdn.amcharts.com/lib/4/themes/animated.js"></script>

<div id="chartdiv" style="width: 100%; height: 400px;"></div>

<script>
// Set theme
am4core.useTheme(am4themes_animated);

// Create chart instance
var chart = am4core.createFromConfig({
  // ...
}, "chartdiv", am4charts.PieChart);
</script>

Open in CodePen

(click RERUN or legend items to see how much more nicer interactions feel like now)

Note

Refer to the “Using themes” article for more details.

Nested donut charts

A Pie chart can have more than one PieSeries. To create nested Pie/Donut charts, we simply add multiple PieSeries. (making sure they have their dataFields configured properly to point at correct properties in the data)

We’re not going to bloat this article with a code example. We’re just going to slam you with a live demo:

Open in CodePen

Modifying labels, legend, tooltip

By default Pie chart displays all values - in slice labels, rollover tooltips, legend - as percent.

If you’d rather like to display them as absolute values, or otherwise modify default information, you will need to adjust various settings across your chart.

REQUIRED READING The further info in this chapter relies heavily on the concept of binding text placeholder to data. Make sure you read about Text placeholders before proceeding.

Changing slice label content

Slice label content is regulated by a sample template object of the Pie series, accessible by pieSeries.labels.template.

So, if we’d like to change what is displayed in it we will need to modify label.text property of it:

TypeScript

pieSeries.labels.template.text = "{category}: {value.value}";

JavaScript

pieSeries.labels.template.text = "{category}: {value.value}";

JSON

{
  // ...
  "series": [{
    // ...
    "labels": {
      "text": "{category}: {value.value}"
    }
  }]
}

Changing tooltip content

What goes into tooltip when you hover a Pie slice is regulated by slice template’s tooltipText property.

If you’d like to change it, that’s the property you set:

TypeScript

pieSeries.slices.template.tooltipText = "{category}: {value.value}";

JavaScript

pieSeries.slices.template.tooltipText = "{category}: {value.value}";

JSON

{
  // ...
  "series": [{
    // ...
    "slices": {
      "tooltipText": "{category}: {value.value}"
    }
  }]
}

Changing legend value

Finally, if you’d like to set what value is displayed in the legend, you’ll need to set text for its value labels template:

TypeScript

chart.legend.valueLabels.template.text = "{value.value}";

JavaScript

chart.legend.valueLabels.template.text = "{value.value}";

JSON

{
  // ...
  "legend": {
    "valueLabels": {
      "text": "{value.value}"
    }
  }
}

Chart radius

Normally, a Pie chart will take up 80% of the chart container’s width or height - whichever is smaller.

The extra 20% are for accommodating possible labels and slice pull outs.

Like anything else it is changeable. For that we have chart’s radius property.

It can be either fixed pixel value, or relative value in percents (relative to the space available to the chart).

Say, we have labels disabled and would want our chart reclaim the available space instead. We’d just need to set radius to 100% percent:

TypeScript

chart.radius = am4core.percent(100);

JavaScript

chart.radius = am4core.percent(100);

JSON

{
  // ...
  "radius": "100%"
}

3D Pie chart

A 3D Pie in amCharts 4 is a separate chart type represented by a class PieChart3D. It is almost identical to PieChart, save for a few extra properties that deal with the 3D appearance.

To oversimplify, to convert any regular Pie chart to a 3D Pie chart, slap a “3D” to any class and/or module:

Regular Pie chart	3D Pie chart
am4charts.PieChart	am4charts.PieChart3D
am4charts.PieSeries	am4charts.PieSeries3D
am4charts.Legend	am4charts.Legend (Legend is not 3D; it’s shared across multiple chart types)

Open in CodePen

Grouping small slices

With the help if SliceGrouper plugin, you can make Pie Chart automatically group small slices into “Other” group.

Follow the link above for more information.

Related content

You might also benefit from looking at the following Pie chart related tutorials:

• Labels Inside Pie Chart Slices
• Curved Pie Chart Labels
• Pre-hiding Pie Chart Slices
• Pie chart with pre-pulled slice(s)
• Showing placeholder for empty Pie chart
• Manipulating mouse cursor style
• One pulled slice per Pie chart
• Variable-radius Pie Slices
• Creating Pie Series Animations
• Hiding Small Pie Slices
• Sum label inside a donut chart
• Clustered Pie Charts
• PieChart with too many slices
• Dealing with PieChart labels that don’t fit

Related demos

• Pie chart as bullet
• Dragging slices
• Nested donuts
• Variable radius slices
• Half-circle
• Variable-height 3D slices
• Pre-hidden slices
• Custom external legend