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

    1.0.4 • Public • Published

    Marker Clusterer for Google Maps JavaScript API v3

    npm version GitHub release (latest by date) license

    This is fast marker clustering library. It's working with Google Maps JavaScript API v3 as an alternative to markerclusterer and markerclustererplus libraries from the googlemaps/v3-utility-library package.

    Getting Started

    The Marker Clusterer library can be served from the firebase host. Add the following script tag in your html file

    <script src="">

    Please note that Marker Clusterer implements a google.maps.OverlayView interface, so it must be initialized after the Google Maps JavaScript API v3 is fully loaded.

    Typically Google Maps JavaScript API is loaded in asynchronous way as specified in the official documentation

    <script async defer

    That means we must include clusterer initialization code inside initMap() callback function after map object initialization.


    function initMap() {
      var map = new google.maps.Map(document.getElementById('map'), {
        zoom: 12,
        center:  {lat: 41.3850639, lng: 2.1734035}
      MarkerClusterer.getClusterer().then(Clusterer => {
        if (Clusterer) {
          const clusterer = new Clusterer.Builder(map)
    function createMarkers(clusterer) {
      // TODO add markers to cluster using
      // clusterer.createMarker() method.

    Note that clusterer is loaded asynchronously, so the logic should be implemented once MarkerClusterer.getClusterer() promise is resolved.

    Setting up clusterer

    In order to set up a clusterer you should call MarkerClusterer.getClusterer() method that returns a promise. Once resolved the promise you will have a Clusterer class that should be used to create an instance of clusterer object.

    Code snippet is the following

    MarkerClusterer.getClusterer().then(Clusterer => {
      if (Clusterer) {
        // TODO: create instance of clusterer

    Create instance of clusterer

    In order to create instance of clusterer you must call Builder, the Builder accepts an instance of google.maps.Map as a constructor parameter and allows call several chained functions to establish parameters of clusterer.

    const clusterer = new Clusterer.Builder(map)

    Public methods available for chaining in Builder object

    withGridSize(gridSize: number)
    withMinClusterSize(minClusterSize: number)
    withMaxZoom(maxZoom: number)
    withClassName(className: string)
    withStyles(styles: IStyle[])
    withImagePath(imagePath: string)
    withImageExtension(imageExtension: string)
    withZoomOnClick(zoomOnClick: boolean)
    withAverageCenter(averageCenter: boolean)
    withGridBasedStrategy(gridBased: boolean)

    Interface IStyle

    This interface is used to style the cluster's icons. There is default implementation of styles, but you can override it applying array of styles in Builder object

    interface IStyle {
      url: string;
      height: number;
      width: number;
      textColor?: string;
      anchor?: number[] | null;
      textSize?: number;
      backgroundPosition?: string;

    Adding markers to clusterer

    In order to add markers to the clusterer you should use createMarker() method. This method accepts parameter of type google.maps.MarkerOptions

    var marker = clusterer.createMarker({
        position: {lat: 41.3850639, lng: 2.1734035},
        map: map,
        title: 'Hello World!'

    Public methods available on clusterer object

    setVisible(v: boolean): void;
    getTotalClusters(): number;
    getClustererBounds(): google.maps.LatLngBounds;
    getMarkersBounds(): google.maps.LatLngBounds;
    getExtendedBounds(bounds: google.maps.LatLngBounds): google.maps.LatLngBounds;
    redraw(): void;
    destroy(): void;
    createMarker(options: google.maps.MarkerOptions): google.maps.Marker;
    clearMarkers(): void;


    The live demo is available at

    AngularJS example is available at Plunker


    The source code of this library is licensed under the MIT License.


    npm i googlemaps-points-clusterer

    DownloadsWeekly Downloads






    Unpacked Size

    268 kB

    Total Files


    Last publish


    • andreyh13