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/markerclustererplus has changed in a number of ways from @googlemaps/markerclustererplus.
- The
MarkerClustererclass now accepts analgorithmandrendererparameter 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
MarkerClustereraccepts a single options argument instead of positional parameters. - The traditional
GridAlgorithmis 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
MarkerClustererclass is still an instance ofgoogle.maps.OverlayView, but usesgoogle.maps.Markers instead ofgoogle.maps.Overlayto render the clusters. This solves issues related to the usage of map panes and click handlers. - @googlemaps/markerclusterer supports Marker and Map a11y improvements.
172 Dec 8, 2022
770 Jan 1, 2023
649 Dec 21, 2022
89 Dec 22, 2022
11 Dec 29, 2022
9.7k Dec 26, 2022
127 Dec 15, 2022
163 Dec 17, 2022
1.6k Jan 7, 2023
306 Dec 22, 2022
31 Nov 17, 2022
3.2k Jan 2, 2023
27 Nov 9, 2022
2 Oct 25, 2021
3 Sep 30, 2022
111 Dec 15, 2022
9 Dec 28, 2022