TypeScript icon, indicating that this package has built-in type declarations

2.5.3 • Public • Published

Google Maps JavaScript MarkerClusterer

npm Build Release codecov GitHub contributors semantic-release


The library creates and manages per-zoom-level clusters for large amounts of markers.

Try the demo


See the history section and migration section for how this library relates to @google/markerclusterer and @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.

<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>

When adding via unpkg, the MarkerClusterer can be accessed at markerClusterer.MarkerClusterer.


This library uses the official TypeScript typings for Google Maps Platform, @types/google.maps.

npm i -D @types/google.maps


The reference documentation is generated from the TypeScript definitions.


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


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.

Package Sidebar


npm i @googlemaps/markerclusterer

Weekly Downloads






Unpacked Size

494 kB

Total Files


Last publish


  • wangela
  • google-wombot