Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Marker Clustering

  • This tutorial demonstrates how to use marker clusters to manage and display a large number of markers on a Google Map, enhancing visual clarity and performance.

  • The@googlemaps/markerclusterer library is used in conjunction with the Maps JavaScript API to group nearby markers into clusters.

  • Clusters automatically adjust as you zoom in and out, revealing individual markers at closer zoom levels and consolidating them into clusters at further zoom levels.

  • You can customize the appearance of clusters and modify the clustering algorithm to suit your specific needs.

  • The tutorial provides code samples and links to further resources for implementation and customization.

Select platform:AndroidiOSJavaScript

Overview

This tutorial shows you how to use marker clusters to display a large number of markers on a map. You can use the@googlemaps/markerclusterer library in combination with the Maps JavaScript API to combine markers of close proximity into clusters, and simplify the display of markers on the map.

To see how marker clustering works, view the map below.

The number on a cluster indicates how many markers it contains. Notice that as you zoom into anyof the cluster locations, the number on the cluster decreases, and you begin to see the individualmarkers on the map. Zooming out of the map consolidates the markers into clusters again.

The sample below shows the entire code you need to create this map.

TypeScript

import{MarkerClusterer}from"@googlemaps/markerclusterer";asyncfunctioninitMap(){// Request needed libraries.const{Map,InfoWindow}=awaitgoogle.maps.importLibrary("maps")asgoogle.maps.MapsLibrary;const{AdvancedMarkerElement,PinElement}=awaitgoogle.maps.importLibrary("marker")asgoogle.maps.MarkerLibrary;constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:3,center:{lat:-28.024,lng:140.887},mapId:'DEMO_MAP_ID',});constinfoWindow=newgoogle.maps.InfoWindow({content:"",disableAutoPan:true,});// Create an array of alphabetical characters used to label the markers.constlabels="ABCDEFGHIJKLMNOPQRSTUVWXYZ";// Add some markers to the map.constmarkers=locations.map((position,i)=>{constlabel=labels[i%labels.length];constpinGlyph=newgoogle.maps.marker.PinElement({glyph:label,glyphColor:"white",})constmarker=newgoogle.maps.marker.AdvancedMarkerElement({position,content:pinGlyph.element,});// markers can only be keyboard focusable when they have click listeners// open info window when marker is clickedmarker.addListener("click",()=>{infoWindow.setContent(position.lat+", "+position.lng);infoWindow.open(map,marker);});returnmarker;});// Add a marker clusterer to manage the markers.newMarkerClusterer({markers,map});}constlocations=[{lat:-31.56391,lng:147.154312},{lat:-33.718234,lng:150.363181},{lat:-33.727111,lng:150.371124},{lat:-33.848588,lng:151.209834},{lat:-33.851702,lng:151.216968},{lat:-34.671264,lng:150.863657},{lat:-35.304724,lng:148.662905},{lat:-36.817685,lng:175.699196},{lat:-36.828611,lng:175.790222},{lat:-37.75,lng:145.116667},{lat:-37.759859,lng:145.128708},{lat:-37.765015,lng:145.133858},{lat:-37.770104,lng:145.143299},{lat:-37.7737,lng:145.145187},{lat:-37.774785,lng:145.137978},{lat:-37.819616,lng:144.968119},{lat:-38.330766,lng:144.695692},{lat:-39.927193,lng:175.053218},{lat:-41.330162,lng:174.865694},{lat:-42.734358,lng:147.439506},{lat:-42.734358,lng:147.501315},{lat:-42.735258,lng:147.438},{lat:-43.999792,lng:170.463352},];initMap();
Note: Read theguide on using TypeScript and Google Maps.

JavaScript

import{MarkerClusterer}from"@googlemaps/markerclusterer";asyncfunctioninitMap(){// Request needed libraries.const{Map,InfoWindow}=awaitgoogle.maps.importLibrary("maps");const{AdvancedMarkerElement,PinElement}=awaitgoogle.maps.importLibrary("marker",);constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:3,center:{lat:-28.024,lng:140.887},mapId:"DEMO_MAP_ID",});constinfoWindow=newgoogle.maps.InfoWindow({content:"",disableAutoPan:true,});// Create an array of alphabetical characters used to label the markers.constlabels="ABCDEFGHIJKLMNOPQRSTUVWXYZ";// Add some markers to the map.constmarkers=locations.map((position,i)=>{constlabel=labels[i%labels.length];constpinGlyph=newgoogle.maps.marker.PinElement({glyph:label,glyphColor:"white",});constmarker=newgoogle.maps.marker.AdvancedMarkerElement({position,content:pinGlyph.element,});// markers can only be keyboard focusable when they have click listeners// open info window when marker is clickedmarker.addListener("click",()=>{infoWindow.setContent(position.lat+", "+position.lng);infoWindow.open(map,marker);});returnmarker;});// Add a marker clusterer to manage the markers.newMarkerClusterer({markers,map});}constlocations=[{lat:-31.56391,lng:147.154312},{lat:-33.718234,lng:150.363181},{lat:-33.727111,lng:150.371124},{lat:-33.848588,lng:151.209834},{lat:-33.851702,lng:151.216968},{lat:-34.671264,lng:150.863657},{lat:-35.304724,lng:148.662905},{lat:-36.817685,lng:175.699196},{lat:-36.828611,lng:175.790222},{lat:-37.75,lng:145.116667},{lat:-37.759859,lng:145.128708},{lat:-37.765015,lng:145.133858},{lat:-37.770104,lng:145.143299},{lat:-37.7737,lng:145.145187},{lat:-37.774785,lng:145.137978},{lat:-37.819616,lng:144.968119},{lat:-38.330766,lng:144.695692},{lat:-39.927193,lng:175.053218},{lat:-41.330162,lng:174.865694},{lat:-42.734358,lng:147.439506},{lat:-42.734358,lng:147.501315},{lat:-42.735258,lng:147.438},{lat:-43.999792,lng:170.463352},];initMap();
Note: The JavaScript is compiled from the TypeScript snippet.

CSS

/* * Always set the map height explicitly to define the size of the div element * that contains the map. */#map{height:100%;}/* * Optional: Makes the sample page fill the window. */html,body{height:100%;margin:0;padding:0;}

HTML

<html>  <head>    <title>Marker Clustering</title>    <link rel="stylesheet" type="text/css" href="./style.css" />    <script type="module" src="./index.js"></script>  </head>  <body>    <div></div>    <!-- prettier-ignore -->    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>  </body></html>

Try Sample

As a simple illustration, this tutorial adds a set of markers to the map using thelocations array. You can use other sources to get markers for your map.For more information, read the guide tocreating markers.

Add a marker clusterer

Follow the steps below to add a marker clusterer:

  1. Add the marker clustering library to your page or application. The library is available on NPM at@googlemaps/markerclusterer and in therepository on GitHub.

    NPM

    Install the latest version of the@googlemaps/markerclusterer library using NPM.

    npminstall@googlemaps/markerclusterer

    CDN

    The script below loads the latest 1.x.x version of the library from theunpkg.com CDN.

    <script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
  2. Add a marker clusterer in your app.

    The code below adds a marker clusterer to the map.

    NPM

    import{MarkerClusterer}from"@googlemaps/markerclusterer";constmarkerCluster=newMarkerClusterer({markers,map});

    CDN

    When accessed with the CDN, the library is available under themarkerClusterer global.

    constmarkerCluster=newmarkerClusterer.MarkerClusterer({markers,map});

    This sample passes themarkers array to theMarkerClusterer.

  3. Customize the marker clusterer.

Learn more

You can view more complex examples of marker clustering in therepository on GitHub and read thereference documentation for the library.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.