Available from V 3.5


Provides a MarkerClusterGroup object. This allows markers that are close to each other to be grouped together into a cluster, depending on the zoom level in the map, to be dissolve again. A cluster is displayed as one element on the map and include markers.

var markers = ym.markerClusterGroup({
	spiderfyOnMaxZoom: false,
	showCoverageOnHover: false,
	zoomToBoundsOnClick: false


Factory: ym.markerClusterGroup(options)

Instantiates a MarkerClusterGroup object with optionally the MarkerClusterGroup options described below.


Name Description Data type Default value
options [optional] Object null

Parameter: options

Name Description Data type Default value
showCoverageOnHover When hovering the mouse over a cluster, the boundaries of the cluster are drawn as a polygon. bool true
zoomToBoundsOnClick Clicking on a cluster with the mouse activates zooms into the cluster boundaries. bool true
spiderfyOnMaxZoom When the last zoom level of the map is reached, clicking on the cluster will cause lines (spider legs) to be drawn apart from the center point when markers are on top of each other on the map. bool true
spiderLegPolylineOptions Allows you to set polyline options to define the appearance of the spider legs. polyline option { weight: 1.5, color: '#222', opacity: 0.5 }
disableClusteringAtZoom Disables clustering above a certain zoom level. The maximum zoom level is 19. See also spiderfyOnMaxZoom. Number none
removeOutsideVisibleBounds Markers and clusters that are not in the field of view of the map are hidden. Enabled for better performance. bool true
maxClusterRadius Specifies the distance in pixels from the central marker covered by the cluster. If the number of pixels is small, several smaller clusters of markers are created. Number 80
polygonOptions Options passed when a ym.Polygon(points, options) is passed for the boundaries. ym.Polygon (points, options) null
singleMarkerMode If activated, all markers are displayed as a cluster with one element. The icon of the markers will be overwritten. bool false
spiderfyDistanceMultiplier Allows to increase the distance of the spider legs to the center. For example, when using large icons for the markers. Number 1
iconCreateFunction Allows to pass a custom function to design custom icons and its content for clustering. For more information, see ym.modules.provider.MarkerCluster with for example the methods getChildCount() and getAllChildMarkers(). function(cluster) {return L.divIcon({ html: '<b>' + cluster.getChildCount() + '</b>' });}</code></td> function (MarkerCluster cluster) null
animate Enables or disables animation when unclustering and merging clusters and spider legs. bool true
animateAddingMarkers If set true, markers added to the MarkerClusterGroup will be added to the cluster by animation. This works only with addLayer and not addLayers. Is disabled by default for better performance. bool false
clusterPane Allows assigning a MapPane where the cluster will be added. A Map Pane allows grouping layers. Pane markerPane
chunkedLoading Enables adding markers in split cycles to prevent the browser window from freezing, in case of large amounts of data. bool false
chunkInterval Time in milliseconds after which the addition of addLayers is paused so that other processes of the page can be performed. Number 200
chunkDelay Time in milliseconds after addLayers is paused that other processes of the page can be executed. Number 50
chunkProgress Callback function that is executed after each chunkInterval. Allows e.g. implementing a progress indicator of the process. function(number MarkersProcessed, number MarkersTotal, number elapsedTimeInMs, layersArray) {} null


Add and remove markers

Name Return Description
addLayer(ILayer layer) this Adds the specified layer with markers to the cluster.
removeLayer(ILayer layer) this Removes from the cluster the specified layer with markers.

Mass add and remove markers

Name Return Description
addLayers(ILayer layer) this Adds the specified layers with markers to the cluster.
removeLayers(ILayer layer) this Removes from the cluster the specified layers with markers.
clearLayers() this Removes from the cluster all layers with markers.

Return of the visible element of a marker

Name Return Description
getVisibleParent(Marker marker) IMarker oder ICluster Returns the visible element if it is visible on the map. Either the marker or the cluster. If the element is not visible, null is returned.

Update cluster icons

Name Return Description
refreshClusters() None Forces all cluster icons in the MarkerClusterGroup to be updated
refreshClusters(Marker) None Forces the update of the cluster icon in which the passed marker is located.
refreshClusters(Marker[]) None Forces all cluster icons containing the passed markers to be updated.
refreshClusters(LayerGroup) None Forces all cluster icons related to the markers of the given LayerGroup to be updated.

Other methods

Name Return Description
hasLayer(Layer) Layer Returns true if the layer (marker) is in the MarkerClusterGroup.
zoomToShowLayer(Layer, callback) None Zooms to the passed marker and calls the callback function when the marker becomes visible on the map.


Marker events like click, mouseover, etc. are associated with the markers in the cluster. To register events for a cluster, proceed as follows: 'cluster' + '', for example: clusterclick, clustermouseover, clustermouseout.

markers.on('clusterclick', function (a) {
	console.log('marker ' + a.layer);

Ereignis Ereignis-Objekt Beschreibung
clusterclick MouseEvent Triggered when a cluster is clicked with the mouse.
clustermouseover MouseEvent Is triggered when the mouse is moved into the element boundaries of the cluster.
clustermouseout MouseEvent Triggered when the element boundaries of the cluster are left with the mouse.
animationend Event Triggered when the animation for the cluster merge or unmerge is completed.
spiderfied ClusterEvent Triggered when overlapping markers on the map with lines (spider legs) are pulled apart from the center point. (Includes markers and cluster attributes).
unspiderfied ClusterEvent Triggered when overlapping markers on the map are re-clustered with lines (spider legs) from the center point. (Includes markers and cluster attributes).