Leaflet.MarkerCluster.Freezable
Sub-plugin for Leaflet.markercluster
plugin (MCG in short); adds the ability to freeze clusters at a specified zoom.
Leaflet.markercluster plugin
provides beautiful animated Marker Clustering functionality.
Leaflet is the leading open-source JavaScript library
for mobile-friendly interactive maps.

Requirements
This plugin is compatible with the following combinations:
Leaflet | Leaflet.markercluster | Leaflet.MarkerCluster.Freezable |
---|
1.0.0 → 1.2.0
|
1.0.4 → 1.1.0
|
1.0.0
|
1.0.0 → 1.0.3
|
0.1.1
|
0.7.7
|
0.5.0
|
Demos
Usage instructions
Quick Guide
HTML:
<script src="leaflet.markercluster.freezable.js"></script>
JavaScript:
var map = L.map("map"),
mcg = L.markerClusterGroup(options);
mcg.addLayers(arrayOfMarkers);
mcg.addTo(map);
mcg.freezeAtZoom(15);
mcg.freezeAtZoom("maxKeepSpiderfy");
mcg.freezeAtZoom("max");
mcg.unfreeze();
mcg.disableClusteringKeepSpiderfy();
mcg.disableClustering();
mcg.enableClustering();
When frozen / disabled, clusters will no longer split / merge on map zoom, but
retain their status as if they were on the specified zoom level. They will
directly spiderfy when clicked on, instead of zooming to bounds (since zooming
will not make them split apart).
In particular, freezing at maxZoom + 1
removes all clusters.
Freezing at maxZoom
removes all clusters except the bottom-most ones, so that
user can still spiderfy closely positioned markers.
CAUTION: make sure your operations makes sense before freezing to high zoom
whereas the map is at a low zoom. It may have to load thousands of markers
suddenly!
Note: while frozen, MCG will continue removing clusters and markers which are
far from the view port, accordingly with removeOutsideVisibleBounds
option.
Installing the sub-plugin
Local copy
CDN
You can alternatively use the free unpkg CDN service, but keep in mind that it "is a free, best-effort service and cannot provide any uptime or support guarantees".
<script src="https://unpkg.com/leaflet.markercluster.freezable@1.0.0/dist/leaflet.markercluster.freezable.js"></script>
npm
-
Add this package to your project:
$ npm install leaflet.markercluster.freezable --save
-
If you are using a bundling tool, import in your JavaScript.
It only performs the side effect of adding new methods to L.markerClusterGroup
,
so you do not need to store it into a local variable or import a namespace.
require('leaflet.markercluster.freezable');
import 'leaflet.markercluster.freezable';
Creation
Simply use the the regular L.markerClusterGroup
factory, as Freezable plugin
directly adds new methods to Leaflet.markercluster:
var mcg = L.markerClusterGroup(options);
mcg.addTo(map);
API Reference
Methods
freezeAtZoom( <Number> or <String> or <Boolean> frozenZoom? ) | this | Freezes clusters at specified zoom, current zoom, or unfreeze. If passed a positive number (including 0), freezes at that zoom. If passed "max" (string), freezes at maxZoom + 1 . If passed "maxKeepSpiderfy" (string), freezes at maxZoom . If passed nothing, undefined , true (boolean) or NaN , freezes at current zoom. If passed false (boolean) or any other non-number, unfreezes. |
unfreeze() | this | Shortcut for freezeAtZoom(false) . |
disableClustering() | this | Shortcut for freezeAtZoom("max") . |
disableClusteringKeepSpiderfy() | this | Shortcut for freezeAtZoom("maxKeepSpiderfy") . |
enableClustering() | this | Shortcut for unfreeze() . |
MCG.Freezable does not provide any extra option or event.
Regular MCG options, events and methods
All regular MCG options,
events and
methods are
available within MCG Layer Support. Refer to Leaflet.markercluster documentation.
Limitations
Freezing at current zoom while not on map
If you request MCG to freeze at current zoom, but MCG is not on any map at that
moment, it will freeze at the zoom the map is at when added to it.
License

Leaflet.MarkerCluster.Freezable is distributed under the
MIT License (Expat type), like
Leaflet.markercluster.
1.0.0 (2017-10-27) for Leaflet 1.0 + MCG >= 1.0.4
Compatible with Leaflet >= 1.0.0 and Leaflet.markercluster >= 1.0.4
Breaking changes:
- Fix compatibility issue with MCG >= 1.0.4; previously non-clustered markers disappear when clusters split #5
Fixes:
Docs:
- Refactor demo page so that it can load selected versions of Leaflet, MCG and MCG.Freezable, as well as locally built
dist
version, therefore obsoleting the debug
pages.
- Move
gh-pages
branch to docs/
folder, so that online demo pages are easier to maintain #9
- Use a build script for README, so that versions are automatically updated #8