Creates and manages per-zoom-level clusters for large amounts of markers.
npm install @appbaseio/googlemaps-markerclusterer
!Build
!Release
!GitHub contributors
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][@google/markerclusterer] and [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
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.
`html`
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.
`sh`
npm i -D @types/google.maps
The reference documentation is generated from the TypeScript definitions.
`js
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.
!Screen Shot 2021-09-28 at 1 41 06 PM
This library has a heritage in [@google/markerclusterer][@google/markerclusterer] and [@googlemaps/markerclustererplus][@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][@google/markerclusterer] was created.
- 201X - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was created.
- 2019 - Libraries were published to NPM.
- 2019 - [@google/markerclusterer][@google/markerclusterer] was deprecated for [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
- 2020 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was refactored to TypeScript.
- 2020 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was moved to a separate repository.
- 2021 - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] was rewritten as [@googlemaps/markerclusterer (new)][@googlemaps/markerclusterer].
- TBD - [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus] is deprecated for [@googlemaps/markerclusterer (new)][@googlemaps/markerclusterer].
The API of [@googlemaps/markerclusterer][@googlemaps/markerclusterer] has changed in a number of ways from [@googlemaps/markerclustererplus][@googlemaps/markerclustererplus].
- The MarkerClusterer class now accepts an algorithm and renderer parameter to allow for more flexibility. The interface looks like the following:
`js`
{
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.GridAlgorithm
- The traditional is still supported, but is not the default. The default is supercluster which uses k-d trees for improved performance.MarkerClusterer
- Styling of clusters has been simplifed and moved to the renderer interface.
- The class is still an instance of google.maps.OverlayView, but uses google.maps.Markers instead of google.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.
[@googlemaps/markerclustererplus]: https://www.npmjs.com/package/@googlemaps/markerclustererplus
[@google/markerclusterer]: https://www.npmjs.com/package/@google/markerclusterer
[@googlemaps/markerclusterer]: https://www.npmjs.com/package/@googlemaps/markerclusterer