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 an algorithm and renderer 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 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.

vicb/js-markerclusterer