Clustered polygons

Explore in the sandboxView live

This sample demonstrates how to enable clustering on a polygon layer representing swimming pool locations in a city. Clustering is configured in the featureReduction property of the layer and setting its type to cluster.

Without clustering, it is very difficult to see individual pool locations at smaller scales (see the image on the left). The image on the right shows that clustering allows you to view where data exist at small scales. It also makes it easy to see the spatial distribution of pools across the city. Note that individual pool locations are still represented with marker symbols when clustering is enabled.

Clustering disabled	Clustering enabled

When clustering polygon or polyline layers, you must define a cluster renderer for clusters to be visible in the view. The cluster renderer should complement the layer's renderer. For example, the cluster renderer in this app is a simple renderer that displays a single symbol for each cluster that matches the color of the simple renderer of the underlying layer.

Use dark colors for code blocksCopy
// Individual swimming pool locations will be displayed
// as simple markers with a royalblue fill color
layer.renderer = {
  type: "simple",
  symbol: {
    type: "simple-fill",
    color: "royalblue",
    outline: {
      width: 0.5,
      color: "rgba(255,255,255,0.3)"
    }
  }
};

// Polygons will be aggregated into clusters
// and represented as marker symbols
layer.featureReduction = {
  type: "cluster",
  // Note the symbol type of the cluster renderer must be
  // a marker symbol; in this case it matches the color
  // of the fill symbol in the layer's renderer
  renderer: {
    type: "simple",
    symbol: {
      type: "simple-marker",
      color: "royalblue",
      outline: {
        width: 0.5,
        color: "rgba(255,255,255,0.3)"
      }
    }
  },

  // cluster visibility will be turned off at this scale
  // and features with fill symbols will be displayed
  // as defined in the layer's renderer
  maxScale: 4514,
};

Best practices for clustering lines and polygons

Use a cluster 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 as 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).
As a result, 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).