Point clustering - basic configuration

Explore in the sandboxView live

This sample demonstrates how to enable point clustering on a GeoJSONLayer. Clustering is a method of reducing points in a FeatureLayer, CSVLayer, GeoJSONLayer, WFSLayer, or OGCFeatureLayer by grouping them based on their spatial proximity to one another. Typically, clusters are proportionally sized based on the number of features within each cluster.

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

   
1
2
3
layer.featureReduction = {
  type: "cluster"
};

The feature reduction property gives you control over many other cluster properties. The clusterRadius defines area of influence that determines each cluster's region for including features. You may also define popupTemplates and labels for clusters that summarize the features comprised by the cluster.

Configure clustering
44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79 79
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="initial-scale=1,maximum-scale=1,user-scalable=no"
  />

    <title>Point clustering - basic configuration | Sample | ArcGIS API for JavaScript 4.21</title>

    <style>
      html,
      body,
      #viewDiv {
        padding: 0;
        margin: 0;
        height: 100%;
        width: 100%;
        background: rgba(50,50,50);
      #infoDiv {
        padding: 10px;
    </style>

    <link rel="stylesheet" href="https://js.arcgis.com/4.21/esri/themes/dark/main.css" />
    <script src="https://js.arcgis.com/4.21/"></script>

    <script>
      require([
        "esri/Map",
        "esri/layers/FeatureLayer",
        "esri/layers/GeoJSONLayer",
        "esri/views/MapView",
        "esri/widgets/Legend",
        "esri/widgets/Expand",
        "esri/widgets/Home"
      ], (Map, FeatureLayer, GeoJSONLayer, MapView, Legend, Expand, Home) => {
        // Configures clustering on the layer. A cluster radius
        // of 100px indicates an area comprising screen space 100px
        // in length from the center of the cluster
        const clusterConfig = {
          type: "cluster",
          clusterRadius: "100px",
          // {cluster_count} is an aggregate field containing
          // the number of features comprised by the cluster
          popupTemplate: {
            title: "Cluster summary",
            content: "This cluster represents {cluster_count} earthquakes.",
            fieldInfos: [{
              fieldName: "cluster_count",
              format: {
                places: 0,
                digitSeparator: true
              }
            }]
          },
          clusterMinSize: "24px",
          clusterMaxSize: "60px",
          labelingInfo: [{
            deconflictionStrategy: "none",
            labelExpressionInfo: {
              expression: "Text($feature.cluster_count, '#,###')"
            },
            symbol: {
              type: "text",
              color: "#004a5d",
              font: {
                weight: "bold",
                family: "Noto Sans",
                size: "12px"
              }
            },
            labelPlacement: "center-center",
          }]
        };
        const layer = new GeoJSONLayer({
          title: "Earthquakes from the last month",
          url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.geojson",
          copyright: "USGS Earthquakes",
          featureReduction: clusterConfig,
          // popupTemplates can still be viewed on
          // individual features
          popupTemplate: {
            title: "Magnitude {mag} {type}",
            content: "Magnitude {mag} {type} hit {place} on {time}",
            fieldInfos: [
                fieldName: "time",
                format: {
                  dateFormat: "short-date-short-time"
          renderer: {
            type: "simple",
            field: "mag",
            symbol: {
              type: "simple-marker",
              size: 4,
              color: "#69dcff",
              outline: {
                color: "rgba(0, 139, 174, 0.5)",
                width: 5
        // background layer for geographic context
        // projected to Alaska Polar Stereographic
        const baseLayer = new FeatureLayer({
          portalItem: {
            id: "2b93b06dc0dc4e809d3c8db5cb96ba69"
          legendEnabled: false,
          popupEnabled: false,
          renderer: {
            type: "simple",
            symbol: {
              type: "simple-fill",
              color: [65, 65, 65, 1],
              outline: {
                color: [50, 50, 50, 0.75],
                width: 0.5
          spatialReference: {
            wkid: 5936
        const map = new Map({
          layers: [baseLayer, layer]
        const view = new MapView({
          container: "viewDiv",
          extent: {
            spatialReference: {
              wkid: 5936
            xmin: 1270382,
            ymin: -1729511,
            xmax: 2461436,
            ymax: -953893
          spatialReference: {
            // WGS_1984_EPSG_Alaska_Polar_Stereographic
            wkid: 5936
          constraints: {
            minScale: 15469455
          map: map
        view.ui.add(new Home({
          view: view
        }), "top-left");
        const legend = new Legend({
          view: view,
          container: "legendDiv"
        const infoDiv = document.getElementById("infoDiv");
        view.ui.add(new Expand({
          view: view,
          content: infoDiv,
          expandIconClass: "esri-icon-layer-list",
          expanded: false
        }), "top-left");
        const toggleButton = document.getElementById("cluster");
        // To turn off clustering on a layer, set the
        // featureReduction property to null
        toggleButton.addEventListener("click", () => {
          let fr = layer.featureReduction;
          layer.featureReduction = fr && fr.type === "cluster" ? null : clusterConfig;
          toggleButton.innerText = toggleButton.innerText === "Enable Clustering" ? "Disable Clustering" : "Enable Clustering";
    </script>
  </head>

  <body>
    <div id="viewDiv"></div>
    <div id="infoDiv" class="esri-widget">
      <button id="cluster" class="esri-button">Disable Clustering</button>
      <div id="legendDiv"></div>
    </div>
  </body>
</html>

Suggestions for basic configuration

  • Turn off label deconfliction when labeling clusters with a count in the center of the cluster. If label placement is outside the cluster, keep label deconfliction enabled.
  • Increase the clusterMinSize to fit labels inside smaller clusters (16pt is a good starting point).
  • For larger layers, format the cluster count in the label with either a rounded value or a meaningful abbreviated value (e.g. 10k instead of 10000). See the Point clustering - generate suggested configuration for an example of this.

Point clustering only applies to layers with point geometries in a MapView containing either a SimpleRenderer, UniqueValueRenderer, or a ClassBreaksRenderer. It does not apply to layers with polyline and polygon geometries.

Clustering layers with spatial references other than Web Mercator and WGS-84 is experimental and may not work for every projection. Clustered layers that have spatial references other than Web Mercator or WGS-84 have the same limitations listed in the projection engine documentation.

Click here to read more information about clustering limitations.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.