Pie chart | ArcGIS Maps SDK for JavaScript

Proportion of college undergraduates in different regions, with each slice representing a region and the size of the slice corresponding to the number of undergraduates in that region.

What is a pie chart?

Pie charts group data into slices to visualize part-to-whole relationships, the size of the slices correspond to the proportion of each category to the whole.

Data configurations

This section demonstrates how different data configurations can be used to create various types of pie charts, including configurations with a category field, numeric fields, and both category and numeric fields.

With category field

Pie chart with a category field will display the count of features for each category. A category field must be a string or integer.

The above chart visualizes the proportion of college undergraduates in different regions. Each slice represents a region, with the size of the slice corresponding to the number of undergraduates in that region.

Set the category property to "Region" to specify the category field.

Charts component

29 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Esri Developer Guide: Pie Chart with Category Field</title>
    <style>
      html,
      body,
      arcgis-chart {
        height: 100%;
        margin: 0;
      }
    </style>
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>
  </head>
  <body>
    <arcgis-chart></arcgis-chart>
    <script type="module">
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      const featureLayer = new FeatureLayer({
        portalItem: {
          id: "8871626e970a4f3e9d6113ec63a92f2f",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const pieChartModel = await createModel({ layer: featureLayer, chartType: "pieChart" });

      pieChartModel.category = "Region";
11 collapsed lines

      pieChartModel.labelCharacterLimit = 20;
      pieChartModel.dataLabelsVisibility = true;
      pieChartModel.alignDataLabels = true;
      pieChartModel.optimizeDataLabelsOverlapping = true;
      pieChartModel.titleText = "Percentage of College Undergraduates by Region";
      chartElement.model = pieChartModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

With numeric fields

Pie chart with only numeric fields will display each numeric field as its own slice, with values aggregated using the sum.

The above chart visualizes the population by age groups in the United States. Each slice represents an age group, with the size of the slice corresponding to the population in that age group.

Set the mode property to "fields" to specify that each numeric field should be treated as its own slice.
Set the numericFields property to specify the numeric fields.

Charts component

29 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Esri Developer Guide: Pie Chart with Numeric Fields</title>
    <style>
      html,
      body,
      arcgis-chart {
        height: 100%;
        margin: 0;
      }
    </style>
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>
  </head>
  <body>
    <arcgis-chart></arcgis-chart>
    <script type="module">
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      const featureLayer = new FeatureLayer({
        portalItem: {
          id: "a8dd07c93e654c76b68951795a20a295",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const pieChartModel = await createModel({ layer: featureLayer, chartType: "pieChart" });

      pieChartModel.mode = "fields";
      pieChartModel.numericFields = [
        "AGE_UNDER5",
        "AGE_5_17",
        "AGE_18_21",
        "AGE_22_29",
        "AGE_30_39",
        "AGE_40_49",
        "AGE_50_64",
        "AGE_65_UP",
      ];
10 collapsed lines

      pieChartModel.titleText = "Population by Age Groups in the United States";
      pieChartModel.dataLabelsVisibility = true;
      pieChartModel.legendTitleText = "Age Group";
      pieChartModel.legendPosition = "left";
      chartElement.model = pieChartModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

With category and numeric fields

When both category and numeric fields are specified, the slices are aggregated by sum: the numeric field is summed for each unique value, and those totals are used to calculate each slice’s proportion.

Set the category property to "Region" to specify the category field.
Set the numericFields property to ["Undergrads"] to specify the numeric field to be aggregated for slice size.

Charts component

29 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Esri Developer Guide: Pie Chart with Category and Numeric Fields</title>
    <style>
      html,
      body,
      arcgis-chart {
        height: 100%;
        margin: 0;
      }
    </style>
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>
  </head>
  <body>
    <arcgis-chart></arcgis-chart>
    <script type="module">
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      const featureLayer = new FeatureLayer({
        portalItem: {
          id: "8871626e970a4f3e9d6113ec63a92f2f",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const pieChartModel = await createModel({ layer: featureLayer, chartType: "pieChart" });

      pieChartModel.category = "Region";
      pieChartModel.numericFields = ["Undergrads"];
13 collapsed lines

      pieChartModel.labelCharacterLimit = 20;
      pieChartModel.dataLabelsVisibility = true;
      pieChartModel.alignDataLabels = true;
      pieChartModel.optimizeDataLabelsOverlapping = true;
      pieChartModel.titleText = "Sum of College Undergraduates by Region";
      pieChartModel.legendTitleText = "Region";
      pieChartModel.legendPosition = "right";
      chartElement.model = pieChartModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Customization options

Donut chart

A donut chart is a variation of a pie chart with a hollow center, this can improve readability by providing more empty space.

The above chart visualizes the proportion of college undergraduates in different regions with a hollow center.

Set the innerRadiusSize property to a value greater than 0 to create a donut chart.

Charts component

30 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Esri Developer Guide: Pie Chart with Category Field</title>
    <style>
      html,
      body,
      arcgis-chart {
        height: 100%;
        margin: 0;
      }
    </style>
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>
  </head>
  <body>
    <arcgis-chart></arcgis-chart>
    <script type="module">
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      const featureLayer = new FeatureLayer({
        portalItem: {
          id: "8871626e970a4f3e9d6113ec63a92f2f",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const pieChartModel = await createModel({ layer: featureLayer, chartType: "pieChart" });
      pieChartModel.category = "Region";

      pieChartModel.innerRadiusSize = 50;
11 collapsed lines

      pieChartModel.labelCharacterLimit = 20;
      pieChartModel.dataLabelsVisibility = true;
      pieChartModel.alignDataLabels = true;
      pieChartModel.optimizeDataLabelsOverlapping = true;
      pieChartModel.titleText = "Percentage of College Undergraduates by Region";
      chartElement.model = pieChartModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Grouped slices

When a pie chart has many categories, it can be difficult to read. The charts component provides an option to group smaller slices into an “Other” category to improve readability.

The above chart visualizes the proportion of college undergraduates in different regions with smaller slices grouped into an “Other” category.

Set the groupingThreshold property to a value between 0 and 100, any slice with a proportion smaller than the threshold will be grouped into an “Other” category.

Charts component

31 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Esri Developer Guide: Pie Chart with Category and Numeric Fields with Grouping</title>
    <style>
      html,
      body,
      arcgis-chart {
        height: 100%;
        margin: 0;
      }
    </style>
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.1/"></script>
  </head>
  <body>
    <arcgis-chart></arcgis-chart>
    <script type="module">
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
      const featureLayer = new FeatureLayer({
        portalItem: {
          id: "8871626e970a4f3e9d6113ec63a92f2f",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const pieChartModel = await createModel({ layer: featureLayer, chartType: "pieChart" });
      pieChartModel.category = "Region";
      pieChartModel.numericFields = ["Undergrads"];

      pieChartModel.groupingThreshold = 10;
13 collapsed lines

      pieChartModel.labelCharacterLimit = 20;
      pieChartModel.dataLabelsVisibility = true;
      pieChartModel.alignDataLabels = true;
      pieChartModel.optimizeDataLabelsOverlapping = true;
      pieChartModel.titleText = "Sum of College Undergraduates by Region";
      pieChartModel.legendTitleText = "Region";
      pieChartModel.legendPosition = "right";
      chartElement.model = pieChartModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Chart typesLine chart Chart typesScatterplot