Clustering annotations
Combine multiple annotations into a single clustered annotation.
Overview
Annotations display coordinate-specific data on a map, typically in the form of markers or images. To declutter annotation-heavy maps, MapKit JS supports annotation clustering. As the user zooms out on a map that contains annotations, MapKit JS groups individual annotations into a cluster annotation if they collide and if they share the same clusteringIdentifier.
The cluster annotation’s memberAnnotations property lists the individual annotations within the cluster. By default, a cluster annotation’s marker displays its member count.
MapKit JS creates cluster annotations automatically. Although you can’t instantiate a cluster annotation, you can customize the look of cluster annotations by providing a delegate method, annotationForCluster, to the map.
Understand the annotations arrays
Although visible on a map, cluster annotations aren’t members of the map’s annotations array. The annotations that make up the cluster do belong to the annotations array, however, even if they’re not individually visible on the map. For example, the following figure shows a map with annotations A, B, C, D, and E:
[Image]
If the user zooms out so A, B, and C overlap on the map, the annotations combine to create cluster annotation Q, as in the following figure:
[Image]
The map displays annotations Q, D, and E, and the resulting annotation arrays are:
Q.memberAnnotations = [A, B, C];map.annotations = [A, B, C, D, E];
Set cluster annotation properties
Cluster annotations have the same properties as other annotations, but you can’t set some values, including coordinate, clusteringIdentifier, and draggable. Other values have specific defaults as the following table shows:
Property | Default for clustering | Description |
|---|---|---|
The | The annotation title text. | |
“ | The annotation subtitle text. | |
The average of the member annotation coordinates. | The annotation’s coordinate. The system automatically sets the coordinate of a cluster annotation to the average of all of the contained member annotation coordinates. You can’t change this value; therefore, the user can’t ever drag a cluster annotation. | |
| The annotation glyph text. | |
| Determines whether the user may drag the annotation. You can’t modify this property. | |
NA | A flat array containing all annotations within the cluster annotation. Only cluster annotations have a | |
| A shared identifier for all of the member annotations. An annotation needs a |