Google Maps JavaScript MarkerClusterer
Description
The library creates and manages per-zoom-level clusters for large amounts of markers.
See the history section and migration section for how this library relates to @google/markerclusterer and @googlemaps/markerclustererplus.
Install
Available via npm as the package @googlemaps/markerclusterer.
npm i @googlemaps/markerclusterer
Alternativly you may add the umd package directly to the html document using the unpkg link.
<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
When adding via unpkg, the MarkerClusterer
can be accessed at markerClusterer.MarkerClusterer
.
TypeScript
This library uses the official TypeScript typings for Google Maps Platform, @types/google.maps.
npm i -D @types/google.maps
Documentation
The reference documentation is generated from the TypeScript definitions.
Examples
import { MarkerClusterer } from "@googlemaps/markerclusterer";
// use default algorithm and renderer
const markerCluster = new MarkerClusterer({ map, markers });
View the package in action:
-
Algorithm Comparisons - This example demonstrates the different algorithms. Please note that spacing and many other options can be changed for each algorithm.
-
Renderer Usage - This example demonstrates different renderers similar to the image below.
History
This library has a heritage in @google/markerclusterer and @googlemaps/markerclustererplus, originally made available on code.google.com and then transferred to GitHub at https://github.com/googlemaps/v3-utility-library. The following is an approximate timeline.
- 201X - @google/markerclusterer was created.
- 201X - @googlemaps/markerclustererplus was created.
- 2019 - Libraries were published to NPM.
- 2019 - @google/markerclusterer was deprecated for @googlemaps/markerclustererplus.
- 2020 - @googlemaps/markerclustererplus was refactored to TypeScript.
- 2020 - @googlemaps/markerclustererplus was moved to a separate repository.
- 2021 - @googlemaps/markerclustererplus was rewritten as @googlemaps/markerclusterer (new).
- TBD - @googlemaps/markerclustererplus is deprecated for @googlemaps/markerclusterer (new).
Migration
The API of @googlemaps/markerclusterer has changed in a number of ways from @googlemaps/markerclustererplus.
- The
MarkerClusterer
class now accepts analgorithm
andrenderer
parameter to allow for more flexibility. The interface looks like the following:
{
algorithm?: Algorithm;
map?: google.maps.Map;
markers?: google.maps.Marker[];
renderer?: Renderer;
onClusterClick?: onClusterClickHandler;
}
- The
MarkerClusterer
accepts a single options argument instead of positional parameters. - The traditional
GridAlgorithm
is still supported, but is not the default. The default is supercluster which uses k-d trees for improved performance. - Styling of clusters has been simplifed and moved to the renderer interface.
- The
MarkerClusterer
class is still an instance ofgoogle.maps.OverlayView
, but usesgoogle.maps.Marker
s instead ofgoogle.maps.Overlay
to render the clusters. This solves issues related to the usage of map panes and click handlers. - @googlemaps/markerclusterer supports Marker and Map a11y improvements.