Clustering | ArcGIS Maps SDK for JavaScript

Global power plants clustered and categorized by fuel type. Clustering summarizes the layer’s renderer so you can see the spatial density of features at a glance.

What is clustering?

Clustering is a method of reducing features in a layer by grouping them into clusters based on their spatial proximity to one another. Typically, clusters are proportionally sized based on the number of features within each cluster.

This is an effective way to show areas where many points stack on top of one another.

Clustering allows you to effectively visualize where points stack on top of another or are in very close proximity to each other. Use the swipe widget above to compare an unclustered layer of power plants with a clustered version.

Why is clustering useful?

Large layers can be deceptive. What appears to be just a few features can in reality be several thousand. Clustering allows you to visually represent large numbers of features in relatively small areas.

For example, the following map shows the locations of thousands of power plants. In the image below, regions A and B both have a high density of points, making them impossible to compare.

clustering disabled

Figure : Region A and region B both have a high density of points. It is impossible to tell how many points overlap in each area.

However, when clustering is enabled, the user can now clearly see that region B has nearly twice as many points as region A.

classed with no label

Figure : Clustering allows the user to easily compare the density of overlapping features at a glance.

How clustering works

Clustering is configured on the featureReduction property of the layer. You can enable clustering with minimal code by setting the featureReduction type to cluster.

layer.featureReduction = {
  type: "cluster"
};

The featureReduction property gives you control over many other cluster properties. The clusterRadius defines each cluster’s area of influence for including features. You may also define popupTemplates and labels for clusters to summarize the features included in the cluster.

Clustering polylines and polygons

Clustering is typically used to visualize large point layers, but may be used with any geometry type (since version 4.31). In the case of clustering polyline or polygon features, the centroid of the line or polygon is used to determine the cluster in which it is placed. This may lead to some features being placed in unexpected clusters. Because of this, special considerations should be taken when clustering lines and polygons.

Tip

Use the following guidelines when clustering lines or polygons:

When clustering polygon or polyline layers, you must define a cluster renderer for clusters to be visible in the view. Use a renderer that complements the layer’s renderer so that clusters are closely associated with the features they represent.
Avoid clustering polygon and polyline layers with widely varying feature sizes. This can misrepresent the spatial distribution of features. For example, a very large polygon may intersect multiple clusters, but it is only represented in one cluster (the one nearest its centroid).
Clustering lines and polygons works best for small features that are uniform in size. Small features like parcels, buildings, swimming pools, bridges, culverts, or connectors are well-suited for binning at small scales.
Clustering works best at smaller scales (when zoomed out). You should set a maxScale in the feature reduction configuration to disable clustering at larger scales (when zoomed in). This allows you to view features in full fidelity.

See the Clustered polygons sample for a good example of a clustered polygon layer.

Examples

Basic clustering

The following example demonstrates how to enable clustering and configure labels and a popup for displaying the cluster count.

The aggregate fields used by clusters are generated once clustering is enabled on the layer. By default, all clustered layers have a cluster_count aggregate field. This can be used in the labels and the popup for each cluster. Other fields used in the layer’s renderer may be accessible for display in the popup. You can learn more about how to use these in the FeatureReductionCluster.popupTemplate documentation.

See the Related samples and resources below for more examples of how to summarize data within a cluster’s popup.

Global power plants clustered by count.

ArcGIS JS API


36 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5
    <title>Intro to clustering</title>
6

7
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
10

11
    <script type="module">
12
      const [WebMap, MapView, FeatureLayer] = await $arcgis.import([
13
        "@arcgis/core/WebMap.js",
14
        "@arcgis/core/views/MapView.js",
15
        "@arcgis/core/layers/FeatureLayer.js",
16
      ]);
17

18
      const clusteredLayer = new FeatureLayer({
19
        portalItem: {
20
          id: "eb54b44c65b846cca12914b87b315169",
21
        },
22
        renderer: {
23
          type: "simple",
24
          symbol: {
25
            type: "simple-marker",
26
            size: 6,
27
            color: "teal",
28
            outline: {
29
              color: "white",
30
              width: 0.5,
31
            },
32
          },
33
        },
34
      });
35

36

37
      clusteredLayer.featureReduction = {
38
        type: "cluster",
39
        clusterMinSize: 16.5,
40
        // defines the label within each cluster
41
        labelingInfo: [
42
          {
43
            deconflictionStrategy: "none",
44
            labelExpressionInfo: {
45
              expression: "Text($feature.cluster_count, '#,###')",
46
            },
47
            symbol: {
48
              type: "text",
49
              color: "white",
50
              font: {
51
                family: "Noto Sans",
52
                size: "12px",
53
              },
54
            },
55
            labelPlacement: "center-center",
56
          },
57
        ],
58
        // information to display when the user clicks a cluster
59
        popupTemplate: {
60
          title: "Cluster Summary",
61
          content: "This cluster represents <b>{cluster_count}</b> features.",
62
          fieldInfos: [
63
            {
64
              fieldName: "cluster_count",
65
              format: {
66
                places: 0,
67
                digitSeparator: true,
68
              },
69
            },
70
          ],
71
        },
72
      };
52 collapsed lines
73

74

75
      const map = new WebMap({
76
        basemap: {
77
          portalItem: {
78
            id: "75a08e8cd8b64dcfa6945bb7f624ccc5",
79
          },
80
        },
81
        layers: [clusteredLayer],
82
      });
83

84
      const view = new MapView({
85
        container: "viewDiv",
86
        map,
87
        extent: {
88
          spatialReference: {
89
            latestWkid: 3857,
90
            wkid: 102100,
91
          },
92
          xmin: -15327459,
93
          ymin: 2740044,
94
          xmax: -6076744,
95
          ymax: 6878650,
96
        },
97
        popup: {
98
          dockEnabled: true,
99
          dockOptions: {
100
            breakpoint: false,
101
            position: "top-right",
102
          },
103
        },
104
        constraints: {
105
          snapToZoom: false,
106
        },
107
      });
108
    </script>
109

110
    <style>
111
      html,
112
      body,
113
      #viewDiv {
114
        background-color: white;
115
        height: 100%;
116
        margin: 0;
117
      }
118
    </style>
119
  </head>
120

121
  <body>
122
    <div id="viewDiv"></div>
123
  </body>
124
</html>

Suggested cluster defaults

By default, the cluster symbol always summarizes the features in the cluster. When a layer has a UniqueValueRenderer, the symbol of each cluster represents the predominant value of features in the cluster. When a layer has any visual variables applied to it, the average of each variable in the cluster is applied to the cluster symbol. The fields describing the predominant type and average of numeric fields can be referenced in the cluster popup and label.

This example uses smart mapping methods to demonstrate how to generate the suggested cluster configuration specific to the layer’s renderer.

Global power plants clustered and categorized by fuel type. Clustering summarizes the layer renderer so you can see a summary of the features contained by the cluster at a glance.

ArcGIS JS API


90 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5
    <title>Clustering - unique values</title>
6

7
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
10

11
    <script type="module">
12
      const [
13
        WebMap,
14
        MapView,
15
        FeatureLayer,
16
        Legend,
17
        Expand,
18
        clusterLabelCreator,
19
        clusterPopupCreator,
20
      ] = await $arcgis.import([
21
        "@arcgis/core/WebMap.js",
22
        "@arcgis/core/views/MapView.js",
23
        "@arcgis/core/layers/FeatureLayer.js",
24
        "@arcgis/core/widgets/Legend.js",
25
        "@arcgis/core/widgets/Expand.js",
26
        "@arcgis/core/smartMapping/labels/clusters.js",
27
        "@arcgis/core/smartMapping/popup/clusters.js",
28
      ]);
29

30
      const layer = new FeatureLayer({
31
        portalItem: {
32
          id: "eb54b44c65b846cca12914b87b315169",
33
        },
34
      });
35

36
      const map = new WebMap({
37
        basemap: {
38
          portalItem: {
39
            id: "75a08e8cd8b64dcfa6945bb7f624ccc5",
40
          },
41
        },
42
        layers: [layer],
43
      });
44

45
      const view = new MapView({
46
        container: "viewDiv",
47
        map,
48
        extent: {
49
          spatialReference: {
50
            latestWkid: 3857,
51
            wkid: 102100,
52
          },
53
          xmin: -15327459,
54
          ymin: 2740044,
55
          xmax: -6076744,
56
          ymax: 6878650,
57
        },
58
        popup: {
59
          dockEnabled: true,
60
          dockOptions: {
61
            breakpoint: false,
62
            position: "top-right",
63
          },
64
        },
65
        constraints: {
66
          snapToZoom: false,
67
        },
68
      });
69

70
      view.ui.add(
71
        new Expand({
72
          content: new Legend({ view }),
73
          view,
74
        }),
75
        "top-left",
76
      );
77

78
      layer
79
        .when()
80
        .then(generateClusterConfig)
81
        .then((featureReduction) => {
82
          // sets generated cluster configuration on the layer
83
          layer.featureReduction = featureReduction;
84
        })
85
        .catch((error) => {
86
          console.error(error);
87
        });
88

89
      async function generateClusterConfig(layer) {
90

91
        // generates default popupTemplate
92
        const popupTemplate = await clusterPopupCreator
93
          .getTemplates({ layer })
94
          .then((popupTemplateResponse) => popupTemplateResponse.primaryTemplate.value);
95

96
        // generates default labelingInfo
97
        const { labelingInfo, clusterMinSize } = await clusterLabelCreator
98
          .getLabelSchemes({
99
            layer,
100
            view,
101
          })
102
          .then((labelSchemes) => labelSchemes.primaryScheme);
103

104
        // Set this object on layer.featureReduction
105
        return {
106
          type: "cluster",
107
          popupTemplate,
108
          labelingInfo,
109
          clusterMinSize,
110
        };
19 collapsed lines
111

112
      }
113
    </script>
114

115
    <style>
116
      html,
117
      body,
118
      #viewDiv {
119
        background-color: white;
120
        height: 100%;
121
        margin: 0;
122
      }
123
    </style>
124
  </head>
125

126
  <body>
127
    <div id="viewDiv"></div>
128
  </body>
129
</html>

Clusters as pie charts

By default, when a layer has a UniqueValueRenderer or ClassBreaksRenderer, the symbol of each cluster represents the predominant category within the cluster.

You may prefer to visualize clusters of type-based renderers as pie charts rather than the predominant category. To do this, you can call the pieChart.createRendererForClustering method, which will create a pie chart renderer based on the categories defined in a UniqueValueRenderer or a ClassBreaksRenderer.

The fields and renderer returned from this method should be set directly on the FeatureReductionCluster instance on the layer.

const { renderer, fields } = await pieChartRendererCreator.createRendererForClustering({
  layer,
  shape: "donut"
});

layer.featureReduction = {
  type: "cluster",
  fields,
  renderer
}

311 incident reports categorized by fuel type. Clustering summarizes the layer renderer as a pie chart for layers with a UniqueValueRenderer or ClassBreaksRenderer.

API support

The following table describes the geometry and view types that are suited well for each visualization technique.

	2D	Lines	Polygons	Client-side	Server-side
Clustering
Binning
Heatmap
Opacity
Bloom
Aggregation
Thinning	¹	¹	¹	²	³
Visible scale range

Full SupportPartial SupportNo Support

Feature reduction selection not supported
Only by feature reduction selection
Only by scale-driven filter

High density dataIntroduction High density dataBinning

What is clustering?

Why is clustering useful?

How clustering works

Clustering polylines and polygons

Examples

Basic clustering

Suggested cluster defaults

Clusters as pie charts

Related samples and resources

Intro to clustering

Clustered polygons

Override cluster symbol

Clusters as pie charts

Cluster size based on the sum of a field

Clustering with aggregate fields

Clustering - generate suggested configuration

Clustering - filter popup features

Clustering - query clusters

Clustering - advanced configuration

Clustering with visual variables

FeatureReductionCluster

API support