@googlemaps/markerclusterer
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.16 • Public • Published

    Google Maps JavaScript MarkerClusterer

    npm Build Release codecov GitHub contributors semantic-release

    Description

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

    Try the demo

    screenshot

    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.

    Screen Shot 2021-09-28 at 1 43 40 PM

    • Renderer Usage - This example demonstrates different renderers similar to the image below.

    Screen Shot 2021-09-28 at 1 41 06 PM

    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.

    Migration

    The API of @googlemaps/markerclustererplus 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.

    Install

    npm i @googlemaps/markerclusterer

    DownloadsWeekly Downloads

    39,674

    Version

    1.0.16

    License

    Apache-2.0

    Unpacked Size

    997 kB

    Total Files

    28

    Last publish

    Collaborators

    • jpoehnelt
    • google-wombot