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, or OGCFeatureLayer 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.

Clustering is configured in the featureReduction property of the layer. The area of influence that determines each cluster's region for including features is defined by the clusterRadius. You may also define popupTemplates and labels for clusters that summarize the features comprised by the cluster.

layer.featureReduction = {
  type: "cluster",
  clusterRadius: "100px",
  popupTemplate: {
    // cluster_count is an aggregate field indicating the number
    // of features summarized by the cluster
    content: "This cluster represents {cluster_count} earthquakes."
  // You should adjust the clusterMinSize to properly fit labels
  clusterMinSize: "24px",
  clusterMaxSize: "60px",
  labelingInfo: [{
    // turn off deconfliction to ensure all clusters are labeled
    deconflictionStrategy: "none",
    labelExpressionInfo: {
      expression: "Text($feature.cluster_count, '#,###')"
    symbol: {
      type: "text",
      color: "#004a5d",
      font: {
        weight: "bold",
        family: "Noto Sans",
        size: "12px"
    labelPlacement: "center-center",

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.