Gauge | ArcGIS Maps SDK for JavaScript

Average air quality index (AQI) in L.A. County with two guides: one for healthy AQI values and another for unhealthy AQI values.

What is a gauge?

Gauges are used to display a single metric in a quantitative context defined by a range of values. The metric can be derived from a summary statistic or one of a feature’s numeric fields.

Data configurations

This section demonstrates how different data configurations can be used to create various types of gauges.

Statistic gauge

A statistic gauge applies an aggregation method to a numeric field to calculate a single value that is then visualized on the gauge. This type of gauge is useful for displaying overall performance metrics or key indicators based on aggregated data.

The above chart visualizes the average air quality index (AQI) in L.A. County.

Set the field property to "MeasuredValue" to specify the numeric field.
Set the aggregationType property to "avg" to calculate the average value.
Set the innerLabelContent property to display the aggregated value inside the gauge.

Charts component

33 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: Statistic Gauge</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: "9f209b07551e4af89477ba4c454058b7",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const gaugeModel = await createModel({
        layer: featureLayer,
        chartType: "gauge",
      });

      gaugeModel.field = "MeasuredValue";
      gaugeModel.aggregationType = "avg";
      gaugeModel.innerLabelContent = { type: "esriTS" };
10 collapsed lines

      gaugeModel.innerRadius = 50;
      gaugeModel.startAngle = -200;
      gaugeModel.endAngle = 20;
      gaugeModel.titleText = "Average Air Quality Index (AQI) in L.A. County";
      chartElement.model = gaugeModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Feature gauge

A feature gauge visualizes individual features from a dataset, allowing you to see how specific data points contribute to the overall metric.

The above chart visualizes the air quality index (AQI) for a specific feature (at index 0) in L.A. County.

Set the field property to "MeasuredValue" to specify the numeric field.
Set the featureIndex property to "0" to specify the feature to visualize.

Charts component

33 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: Feature Gauge</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: "9f209b07551e4af89477ba4c454058b7",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const gaugeModel = await createModel({
        layer: featureLayer,
        chartType: "gauge",
      });

      gaugeModel.field = "MeasuredValue";
      gaugeModel.featureIndex = 0;
11 collapsed lines

      gaugeModel.innerLabelContent = { type: "esriTS" };
      gaugeModel.innerRadius = 50;
      gaugeModel.startAngle = -200;
      gaugeModel.endAngle = 20;
      gaugeModel.titleText = "Air Quality Index (AQI) for Specific Location (index 0) in L.A. County";
      chartElement.model = gaugeModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Customization options

Guides

Guides are used to indicate specific values or ranges on the gauge, providing context for interpreting the metric being visualized. They can be used to highlight thresholds, targets, or performance levels.

The above chart visualizes the AQI in L.A. County with two guides: one for healthy AQI values (0-50) and another for unhealthy AQI values (50-100).

Use the addXAxisGuide method to add guides to the gauge.
Use the setGuideStart and setGuideEnd methods to specify the start and end values for each guide.
Use the setGuideStyle method to customize the appearance of each guide, such as setting the color and opacity.
Repeat the above steps to add multiple guides to the gauge as needed.

Charts component

43 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: Gauge with Guides</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: "9f209b07551e4af89477ba4c454058b7",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const gaugeModel = await createModel({
        layer: featureLayer,
        chartType: "gauge",
      });
      gaugeModel.field = "MeasuredValue";
      gaugeModel.aggregationType = "avg";
      gaugeModel.innerRadius = 50;
      gaugeModel.startAngle = -200;
      gaugeModel.endAngle = 20;
      gaugeModel.needleSymbol = {
        type: "esriSFS",
        color: [255, 0, 0, 255],
      };
      gaugeModel.innerLabelContent = { type: "esriTS" };

      // 0 - 50 guide
      gaugeModel.addXAxisGuide("Guide 1", 0);
      gaugeModel.setGuideStart(0, 0, "x");
      gaugeModel.setGuideEnd(50, 0, "x");
      gaugeModel.setGuideStyle(
        {
          type: "esriSFS",
          color: [0, 228, 0, 100],
        },
        0,
        "x",
      );
      // 50 - 100 guide
      gaugeModel.addXAxisGuide("Guide 2", 1);
      gaugeModel.setGuideStart(50, 1, "x");
      gaugeModel.setGuideEnd(100, 1, "x");
      gaugeModel.setGuideStyle(
        {
          type: "esriSFS",
          color: [255, 255, 0, 100],
        },
        1,
        "x",
      );
7 collapsed lines

      gaugeModel.titleText = "Average Air Quality Index (AQI) in L.A. County";
      chartElement.model = gaugeModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Progress bands

Progress bands are similar to guides but are used to visually represent the progress of a metric towards a target or threshold.

The above chart visualizes the Upper Klamath Lake capacity with two progress bands: one for the current capacity (blue band) and another for the target capacity (grey band).

Set the progressBands property to add progress bands to the gauge.
Set the type property of progressBands to "fixed" to specify that the bands represent fixed ranges of values.
Set the visible property of progressBands to true to make the bands visible on the gauge.
Define the bands property of progressBands to specify the appearance of the target and base bands.

Charts component

37 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: Gauge with Progress Bands</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: "e3bb6dbf5e0e44baad8391c74161198c",
        },
      });
      const chartElement = document.querySelector("arcgis-chart");
      const gaugeModel = await createModel({
        layer: featureLayer,
        chartType: "gauge",
      });
      gaugeModel.field = "PctFull";
      gaugeModel.featureIndex = 0;
      gaugeModel.innerLabelContent = { type: "esriTS" };
      gaugeModel.needleVisibility = false;

      gaugeModel.progressBands = {
        type: "fixed",
        visible: true,
        bands: {
          target: {
            type: "esriSFS",
            color: [33, 150, 243, 255],
          },
          base: {
            type: "esriSFS",
            color: [224, 224, 224, 255],
          },
        },
      };
10 collapsed lines

      gaugeModel.minXBound = 0;
      gaugeModel.maxXBound = 1;
      gaugeModel.labelsIncrement = 0.1;
      gaugeModel.titleText = "Upper Klamath Lake Capacity (%)";
      chartElement.model = gaugeModel;
      chartElement.actionMode = "none";
    </script>
  </body>
</html>

Chart typesCombo bar line chart Chart typesHistogram