leaflet.markercluster.freezable

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

• Leaflet.MarkerCluster.Freezable 1.0.0 (Leaflet 1.2.0 + Leaflet.markercluster 1.1.0)
• Leaflet.MarkerCluster.Freezable 0.1.1 (Leaflet 1.2.0 + Leaflet.markercluster 1.0.3)
• Leaflet.MarkerCluster.Freezable 0.1.1 (Leaflet 0.7.7 + Leaflet.markercluster 0.5.0)

Usage instructions

Quick Guide

HTML:

<!-- After Leaflet and Leaflet.markercluster scripts -->
<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(); // shortcut for mcg.freezeAtZoom(false)

mcg.disableClusteringKeepSpiderfy(); // shortcut for mcg.freezeAtZoom("maxKeepSpiderfy")
mcg.disableClustering(); // shortcut for mcg.freezeAtZoom("max")
mcg.enableClustering(); // alias for mcg.unfreeze()

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

1. Download the "leaflet.markercluster.freezable.js" file from the v1.0.0 release.
2. Place the file alongside your page.
3. Add the script tag (see Quick Guide > HTML) to your page after Leaflet and Leaflet.markercluster scripts.

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".

<!-- After Leaflet script -->
<script src="https://unpkg.com/leaflet.markercluster.freezable@1.0.0/dist/leaflet.markercluster.freezable.js"></script>

npm

1. Add this package to your project:

   $ npm install leaflet.markercluster.freezable --save
   

2. 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');
   // Or with ES6:
   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

Method	Returns	Description
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.

Changelog

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:

• Compatibility with Leaflet.MarkerClusterGroup.LayerSupport sub-plugin #6 and ghybs/Leaflet.MarkerCluster.LayerSupport#13
• Dynamically added marker do not appear if they are out of the initial view port #7

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