Pie chart | ArcGIS Maps SDK for JavaScript

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.

Variations of the pie chart can be created, such as:

With category field:
- With a category field specified via the category property, the pie chart will display the count of features for each category.
With multiple numeric fields:
- With multiple numeric fields specified via the numericFields property, the pie chart shows each field as its own slice, with values aggregated using the sum.
With one category and one numeric field:
- With one category field specified via the category property and one numeric field specified via the numericFields property, the values of the numeric field are summed for each distinct category. These totals are then used to determine each slice’s proportion.

In this tutorial, you will create and customize a pie chart using pie chart model and render it with the <arcgis-chart> component.

Prerequisites

Steps

Create a new pen

Go to CodePen to create a new pen for your application.

Add basic HTML

Define a basic HTML page.

In CodePen > HTML, add HTML to create a basic page.

<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

</head>


<body>

</body>


</html>

Add the ArcGIS Maps SDK for JavaScript script tag

In the <head>, add the <script> tag for the JavaScript Maps SDK.

9 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>
5 collapsed lines

</head>


</html>

Add chart component

In the <body> tag, add the <arcgis-chart> component and specify the layer item ID and chart index.

23 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

</body>
3 collapsed lines


</html>

Component reference (chart)

Add logic to create a chart

Within the <body> tag, add a <script> tag with type="module" to write JavaScript code to create a chart with charts model.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

  </script>
5 collapsed lines

</body>


</html>

Within the <script> tag, use @arcgis.import() to import the createModel function from @arcgis/charts-components and FeatureLayer from @arcgis/core/layers/FeatureLayer.js.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

  </script>
5 collapsed lines

</body>


</html>

Load a feature layer from a portalItem that contains college scorecard data that will be visualized in the pie chart.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "8871626e970a4f3e9d6113ec63a92f2f",
      },
    });

  </script>
5 collapsed lines

</body>


</html>

Use document.querySelector() to select the <arcgis-chart> component.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "8871626e970a4f3e9d6113ec63a92f2f",
      },
    });

    const chartElement = document.querySelector("arcgis-chart");

  </script>
5 collapsed lines

</body>


</html>

Use createModel() to create a new pie chart model with the feature layer. The chart type is set to pieChart.

28 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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" });

  </script>
5 collapsed lines

</body>


</html>

Customize the pie chart

In this section, we’ll explore how to use various properties and methods from the pie chart model together with the <arcgis-chart> component to render the pie chart.

We will use a category field and a numeric field to visualize the proportions of college undergraduates by region.

First, set the category property to the field name Region. In doing so, the pie chart will group data by different regions.

Then set the numericFields property to an array containing the field name Undergrads, the pie chart will aggregate the total number of undergraduates for each region to determine the proportion of each slice.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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"];

8 collapsed lines
    chartElement.model = pieChartModel;

  </script>

</body>


</html>

Next, enable data labels by setting the dataLabelsVisibility property to true.

You can also customize how data labels are displayed by setting the displayType property to "both" to show both value and percentage, set the labelCharacterLimit property to 20 to limit the number of characters shown in each label.

Additionally, set the alignDataLabels property to true to align labels neatly and set the optimizeDataLabelsOverlapping property to true to reduce overlapping labels.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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.displayType = "both";
    pieChartModel.labelCharacterLimit = 20;
    pieChartModel.dataLabelsVisibility = true;
    pieChartModel.alignDataLabels = true;
    pieChartModel.optimizeDataLabelsOverlapping = true;

8 collapsed lines
    chartElement.model = pieChartModel;

  </script>

</body>


</html>

By modifying the innerRadiusSize property, pie chart can be transformed into a donut chart with hollow centers.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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.displayType = "both";
    pieChartModel.labelCharacterLimit = 20;
    pieChartModel.dataLabelsVisibility = true;
    pieChartModel.alignDataLabels = true;
    pieChartModel.optimizeDataLabelsOverlapping = true;

    pieChartModel.innerRadiusSize = 50;

8 collapsed lines
    chartElement.model = pieChartModel;

  </script>

</body>


</html>

Customize other properties such as titleText, legendTitleText, and legendPosition to enhance the appearance of the pie chart.

43 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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.displayType = "both";
    pieChartModel.labelCharacterLimit = 20;
    pieChartModel.dataLabelsVisibility = true;
    pieChartModel.alignDataLabels = true;
    pieChartModel.optimizeDataLabelsOverlapping = true;

    pieChartModel.innerRadiusSize = 50;

    pieChartModel.titleText = "Sum of College Undergraduates by Region";
    pieChartModel.legendTitleText = "Region";
    pieChartModel.legendPosition = "right";
9 collapsed lines

    chartElement.model = pieChartModel;

  </script>

</body>


</html>

Set the model property of the chartElement to the pieChartModel to apply the configurations and render the chart.

58 collapsed lines
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>
    ArcGIS Maps SDK for JavaScript Tutorials: Pie chart
  </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.0/"></script>

</head>


<body>

  <arcgis-chart></arcgis-chart>

  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    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.displayType = "both";
    pieChartModel.labelCharacterLimit = 20;
    pieChartModel.dataLabelsVisibility = true;
    pieChartModel.alignDataLabels = true;
    pieChartModel.optimizeDataLabelsOverlapping = true;

    pieChartModel.innerRadiusSize = 50;

    pieChartModel.titleText = "Sum of College Undergraduates by Region";
    pieChartModel.legendTitleText = "Region";
    pieChartModel.legendPosition = "right";

    chartElement.model = pieChartModel;
7 collapsed lines

  </script>

</body>


</html>

Run the app

In CodePen, you should see a pie chart with a hollow center showing the total number of college undergraduates by region, with data labels displaying both value and percentage for each slice.

What’s next?

Learn how to use additional SDK features and ArcGIS services in these tutorials: