Noodles Practicing Medicine

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

    2.0.14 • 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=""></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 and then transferred to GitHub at 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.


    npm i @googlemaps/markerclusterer

    DownloadsWeekly Downloads






    Unpacked Size

    769 kB

    Total Files


    Last publish


    • wangela
    • google-wombot