Skip To Content

Configure clustering (Map Viewer)

If your map has a layer with a large number of points, you can configure clustering to visually extract meaningful information from the data. When you enable clustering, Map Viewer (formerly a separate beta installation but now included with the portal automatically) groups point features that are within a certain distance of one another on the map into one symbol. Clustering allows you to see patterns in the data that are difficult to visualize when a layer contains hundreds or thousands of points that overlap and cover each other.


For recommendations on applying clustering to high-density datasets, see Best practices for visualizing high-density data.

Clusters are represented by proportionally sized symbols based on the number of point features in each cluster. Smaller cluster symbols have fewer points, while larger cluster symbols have more points. You can adjust the size range applied to the cluster symbols.

Clustering is applied dynamically at multiple scales, which means that as you zoom out, more points are aggregated into fewer groups, and as you zoom in, more cluster groups are created. When you zoom to a level where the clustering area around one point feature no longer contains other features, that point feature is not clustered; it is displayed as a single point feature with the styling options applied to the layer. You can adjust the number of point features grouped into clusters by setting the cluster radius.

When you enable clustering on a point layer, a label is displayed for each cluster. A default cluster pop-up also appears when you click a cluster on the map. You can customize the cluster pop-up and labels.

Enable clustering

When you enable clustering on a point layer, clusters automatically appear on the map using a default configuration. As you make changes to the cluster settings, the changes are immediately shown on the map. This allows you to experiment with cluster radius and other settings to achieve the desired look and message of your map.

To enable clustering on a point layer, do the following:

  1. Confirm that you are signed in and, if you want to save your changes, that you have privileges to create content.
  2. In Map Viewer, open the map containing the layer or add the layer directly.
  3. On the Contents (dark) toolbar, click Layers Layers.
  4. In the Layers pane, select the layer on which you want to enable clustering.
  5. On the Settings (light) toolbar, click Clustering Clustering.
  6. In the Clustering pane, turn on the Enable clustering toggle button.
  7. Optionally, adjust the Cluster radius slider to change the number of features that are grouped into a cluster.

    Specify a lower cluster radius to group fewer features into each cluster. Specify a higher cluster radius to group more features into each cluster.

  8. Optionally, adjust the Size range slider to set the minimum and maximum cluster size.
  9. Optionally, customize the cluster labels.
  10. Optionally, customize the cluster pop-ups.
  11. Optionally, change the formatting of fields in the clusters.
  12. Close the Clustering pane when you're finished.

Configure cluster labels

Labeling clusters is similar to labeling individual features in a layer. You control the label style—font, text size, placement, and so on. You can keep the labels simple by showing the number of features in each cluster, or, if the layer is styled using an attribute, you can use this attribute for the cluster label. For example, if the layer shows parcels by their value per square foot, you can configure the cluster label to show the average value per square foot of all the points in each cluster. Map Viewer also allows you to use a label filter to only display labels on clusters that meet the filter criteria.

Configuring label classes allows you to further customize cluster labels. For example, you can use label classes to label each cluster based on two attributes, such as the average earthquake magnitude and the earthquake count, using a different label style for each attribute. Cluster label classes are configured in the same way as label classes for features.


Any unclustered point feature displays a feature label if feature labels are enabled for the layer.

To configure cluster labels for a point layer, do the following:

  1. Follow the first six steps of the Enable clustering section above.
  2. In the Clustering pane, click Cluster label.
  3. In the Label features pane, turn on the Enable labels toggle button.
  4. Optionally, click Add label class to configure label classes, and specify the options for each class, as described in the next step.
  5. Customize the cluster labels by doing any of the following:

    See Configure labels for more information about label configuration.

    • Click the Label field selector, select a different field for the label, and click Replace.

      This option is only available if the layer is styled using an attribute. If it's not, you can display the number of features as the cluster label.


      You can use a custom attribute expression written in Arcade instead of an attribute field. Click Use expression Use expression and use the editor window to create the expression.

      You can also use existing expressions to build new expressions; however, some variables may not work in all profiles—for example, an expression created for pop-ups may not work for styles. To use an existing expression, select it from the Existing tab in the editor window.

    • Click Edit label filter, click Add expression, and set up a filter fo display labels on a subset of clusters. For more information, see Apply filters.
    • Click Edit label style. In the Label style window, change the label style options, including the font, text size and color, placement, offsets, and halo effect.
    • Adjust the Visible range slider to change the visible range for the cluster labels.

Configure cluster pop-ups

Cluster pop-ups appear when you click a cluster on the map. The information displayed in cluster pop-ups depends on the style applied to the layer. For example, if the Predominant category style is applied, the default cluster pop-up includes the value of the predominant attribute for each cluster. You can customize the cluster pop-ups to suit your needs.


Clicking an unclustered point feature displays a feature pop-up if feature pop-ups are enabled for the layer.

To configure cluster pop-ups, do the following:

  1. Follow the first six steps of the Enable clustering section above.
  2. In the Clustering pane, click Cluster pop-ups.
  3. In the Pop-ups pane, customize the cluster pop-ups by doing any of the following:

    See Configure pop-ups for more information about pop-up configuration.

    • Optionally, click Manage Expressions to create and modify Arcade expressions to use in the cluster pop-up.
    • Expand the Title section and type a title for the pop-up. You can enter static text and click Add field Add field to select attribute fields from the data.
    • Click the Text content block and click the cluster pop-up text. Change the default content and click OK.
    • Click Add content, click the content type, and add content and media to the cluster pop-up, including images and attribute fields.
    • Drag the content blocks to new positions in the pop-up to change the order.
  4. Click the clusters on the map to view the pop-ups.

    To learn more about the individual features in a cluster, click Browse features on the pop-up and click the forward and back arrows to scroll through information for each feature. To go back to the summary information for the cluster, click the record count between the arrows.


    You can click Dock Dock on the pop-up to lock the pop-up display to the top of the map. Click Undock Undock to display pop-ups near their associated clusters.

Change field formatting

You can change the basic formatting of the fields that are used in cluster labels and pop-ups. For example, you can change the number of decimal places that appear for a numeric field.

To change the basic formatting of the fields, do the following:

  1. Follow the first six steps of the Enable clustering section above.
  2. In the Clustering pane, click Cluster fields.
  3. Select a field, and in the Formatting window, specify the formatting settings. Click Done.
  4. Repeat the previous step for each field whose formatting you want to change.
  5. Click a cluster on the map to see the formatting changes in the pop-up.

    These changes also appear in the cluster labels.