Markers (Legacy)
AI-generated Key Takeaways
Markers on Google Maps identify locations using standard or custom images, with key properties like position, map, and title for customization.
Advanced Markers offer improvements over legacy markers and are available since Maps JavaScript API v3.53.2.
Complex icons can be used for markers, supporting clickable regions and stacking order.
For optimal performance, markers can be optimized for rendering and accessibility should be ensured for keyboard and screen reader users.
Markers can be animated with effects like 'DROP' and 'BOUNCE', controlled using the
animationproperty.
As of February 21st, 2024 (v3.56), google.maps.Marker is deprecated. We encourage you to transition to the newgoogle.maps.marker.AdvancedMarkerElement class. Advanced markers provide substantial improvements over the legacygoogle.maps.Marker class. The minimum version of the Maps JavaScript API withgoogle.maps.marker.AdvancedMarkerElement is 3.53.2. At this time, google.maps.Marker is not scheduled to be discontinued.
Introduction
A marker identifies a location on a map. By default, a marker uses a standard image. Markers can display custom images, in which case they are usually referred to as "icons." Markers and icons are objects of typeMarker. You can set a custom icon within the marker's constructor, or by callingsetIcon() on the marker. See more aboutcustomizing the marker image.
Broadly speaking, markers are a type of overlay. For information on other types of overlay, seeDrawing on the map.
Markers are designed to be interactive. For example, by default they receive'click' events, so you can add an event listener to bring up aninfo window displaying custom information. You can allow users to move a marker on the map by setting the marker'sdraggable property totrue. For more information about draggable markers, seebelow.
Add a marker
Thegoogle.maps.Marker constructor takes a singleMarker options object literal, specifying the initial properties of the marker.
The following fields are particularly important and commonly set when constructing a marker:
position(required) specifies aLatLngidentifying the initial location of the marker. One way of retrieving aLatLngis by using theGeocoding service.map(optional) specifies theMapon which to place the marker. If you do not specify the map on construction of the marker, the marker is created but is not attached to (or displayed on) the map. You may add the marker later by calling the marker'ssetMap()method.
The following example adds a simple marker to a map at Uluru, in the center of Australia:
TypeScript
functioninitMap():void{constmyLatLng={lat:-25.363,lng:131.044};constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:4,center:myLatLng,});newgoogle.maps.Marker({position:myLatLng,map,title:"Hello World!",});}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
functioninitMap(){constmyLatLng={lat:-25.363,lng:131.044};constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:4,center:myLatLng,});newgoogle.maps.Marker({position:myLatLng,map,title:"Hello World!",});}window.initMap=initMap;
Try Sample
In the above example, the marker is placed on the map at construction of the marker using themap property in the marker options. Alternatively, you can add the marker to the map directly by using the marker'ssetMap() method, as shown in the example below:
varmyLatlng=newgoogle.maps.LatLng(-25.363882,131.044922);varmapOptions={zoom:4,center:myLatlng}varmap=newgoogle.maps.Map(document.getElementById("map"),mapOptions);varmarker=newgoogle.maps.Marker({position:myLatlng,title:"Hello World!"});// To add the marker to the map, call setMap();marker.setMap(map);
The marker'stitle will appear as a tooltip.
If you do not wish to pass anyMarker options in the marker's constructor, instead pass an empty object{} in the last argument of the constructor.
Remove a marker
To remove a marker from the map, call thesetMap() method passingnull as the argument.
marker.setMap(null);
Note that the above method does not delete the marker. It removes the marker from the map. If instead you wish to delete the marker, you should remove it from the map, and then set the marker itself tonull.
If you wish to manage a set of markers, you should create an array to hold the markers. Using this array, you can then callsetMap() on each marker in the array in turn when you need to remove the markers. You can delete the markers by removing them from the map and then setting the array'slength to0, which removes all references to the markers.
Customize a marker image
You can customize the visual appearance of markers by specifying animage file orvector-based icon to display instead of the default Google Maps pushpin icon. You can add text with amarker label, and usecomplex icons to define clickable regions, and set the stack order of markers.
Markers with image icons
In the most basic case, an icon can specify an image to use instead of the default Google Maps pushpin icon. To specify such an icon, set the marker'sicon property to the URL of an image. The Maps JavaScript API will size the icon automatically.
TypeScript
// This example adds a marker to indicate the position of Bondi Beach in Sydney,// Australia.functioninitMap():void{constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:4,center:{lat:-33,lng:151},});constimage="https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png";constbeachMarker=newgoogle.maps.Marker({position:{lat:-33.89,lng:151.274},map,icon:image,});}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// This example adds a marker to indicate the position of Bondi Beach in Sydney,// Australia.functioninitMap(){constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:4,center:{lat:-33,lng:151},});constimage="https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png";constbeachMarker=newgoogle.maps.Marker({position:{lat:-33.89,lng:151.274},map,icon:image,});}window.initMap=initMap;
Try Sample
Markers with vector-based icons
You can use custom SVG vector paths to define the visual appearance of markers. To do this, pass aSymbol object literal with the desired path to the marker'sicon property. You can define a custom path usingSVG path notation, or use one of the predefined paths ingoogle.maps.SymbolPath. Theanchor property is required in order for the marker to render correctly when the zoom level changes. Learn more aboutusing Symbols to create vector-based icons for markers (and polylines).
TypeScript
// This example uses SVG path notation to add a vector-based symbol// as the icon for a marker. The resulting icon is a marker-shaped// symbol with a blue fill and no border.functioninitMap():void{constcenter=newgoogle.maps.LatLng(-33.712451,150.311823);constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:9,center:center,});constsvgMarker={path:"M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",fillColor:"blue",fillOpacity:0.6,strokeWeight:0,rotation:0,scale:2,anchor:newgoogle.maps.Point(0,20),};newgoogle.maps.Marker({position:map.getCenter(),icon:svgMarker,map:map,});}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// This example uses SVG path notation to add a vector-based symbol// as the icon for a marker. The resulting icon is a marker-shaped// symbol with a blue fill and no border.functioninitMap(){constcenter=newgoogle.maps.LatLng(-33.712451,150.311823);constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:9,center:center,});constsvgMarker={path:"M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",fillColor:"blue",fillOpacity:0.6,strokeWeight:0,rotation:0,scale:2,anchor:newgoogle.maps.Point(0,20),};newgoogle.maps.Marker({position:map.getCenter(),icon:svgMarker,map:map,});}window.initMap=initMap;
Try Sample
Marker labels
A marker label is a letter or number that appears inside a marker. The marker image in this section displays a marker label with the letter 'B' on it. You can specify a marker label as either a string or aMarkerLabel object that includes a string and other label properties.
When creating a marker, you can specify alabel property in theMarkerOptions object. Alternatively, you can callsetLabel() on theMarker object to set the label on an existing marker.
The following example displays labeled markers when the user clicks on the map:
TypeScript
// In the following example, markers appear when the user clicks on the map.// Each marker is labeled with a single alphabetical character.constlabels="ABCDEFGHIJKLMNOPQRSTUVWXYZ";letlabelIndex=0;functioninitMap():void{constbangalore={lat:12.97,lng:77.59};constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:12,center:bangalore,});// This event listener calls addMarker() when the map is clicked.google.maps.event.addListener(map,"click",(event)=>{addMarker(event.latLng,map);});// Add a marker at the center of the map.addMarker(bangalore,map);}// Adds a marker to the map.functionaddMarker(location:google.maps.LatLngLiteral,map:google.maps.Map){// Add the marker at the clicked location, and add the next-available label// from the array of alphabetical characters.newgoogle.maps.Marker({position:location,label:labels[labelIndex++%labels.length],map:map,});}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// In the following example, markers appear when the user clicks on the map.// Each marker is labeled with a single alphabetical character.constlabels="ABCDEFGHIJKLMNOPQRSTUVWXYZ";letlabelIndex=0;functioninitMap(){constbangalore={lat:12.97,lng:77.59};constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:12,center:bangalore,});// This event listener calls addMarker() when the map is clicked.google.maps.event.addListener(map,"click",(event)=>{addMarker(event.latLng,map);});// Add a marker at the center of the map.addMarker(bangalore,map);}// Adds a marker to the map.functionaddMarker(location,map){// Add the marker at the clicked location, and add the next-available label// from the array of alphabetical characters.newgoogle.maps.Marker({position:location,label:labels[labelIndex++%labels.length],map:map,});}window.initMap=initMap;
Try Sample
Complex icons
You can specify complex shapes to indicate regions that are clickable, and specify how the icons should appear relative to other overlays (their "stack order"). Icons specified in this manner should set theiricon properties to an object of typeIcon.
Icon objects define an image. They also define thesize of the icon, theorigin of the icon (if the image you want is part of a larger image in a sprite, for example), and theanchor where the icon's hotspot should be located (which is based on the origin).
If you are using alabel with a custom marker, you can position the label with thelabelOrigin property in theIcon object.
TypeScript
// The following example creates complex markers to indicate beaches near// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond// to the base of the flagpole.functioninitMap():void{constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:10,center:{lat:-33.9,lng:151.2},});setMarkers(map);}// Data for the markers consisting of a name, a LatLng and a zIndex for the// order in which these markers should display on top of each other.constbeaches:[string,number,number,number][]=[["Bondi Beach",-33.890542,151.274856,4],["Coogee Beach",-33.923036,151.259052,5],["Cronulla Beach",-34.028249,151.157507,3],["Manly Beach",-33.80010128657071,151.28747820854187,2],["Maroubra Beach",-33.950198,151.259302,1],];functionsetMarkers(map:google.maps.Map){// Adds markers to the map.// Marker sizes are expressed as a Size of X,Y where the origin of the image// (0,0) is located in the top left of the image.// Origins, anchor positions and coordinates of the marker increase in the X// direction to the right and in the Y direction down.constimage={url:"https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png",// This marker is 20 pixels wide by 32 pixels high.size:newgoogle.maps.Size(20,32),// The origin for this image is (0, 0).origin:newgoogle.maps.Point(0,0),// The anchor for this image is the base of the flagpole at (0, 32).anchor:newgoogle.maps.Point(0,32),};// Shapes define the clickable region of the icon. The type defines an HTML// <area> element 'poly' which traces out a polygon as a series of X,Y points.// The final coordinate closes the poly by connecting to the first coordinate.constshape={coords:[1,1,1,20,18,20,18,1],type:"poly",};for(leti=0;i <beaches.length;i++){constbeach=beaches[i];newgoogle.maps.Marker({position:{lat:beach[1],lng:beach[2]},map,icon:image,shape:shape,title:beach[0],zIndex:beach[3],});}}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// The following example creates complex markers to indicate beaches near// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond// to the base of the flagpole.functioninitMap(){constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:10,center:{lat:-33.9,lng:151.2},});setMarkers(map);}// Data for the markers consisting of a name, a LatLng and a zIndex for the// order in which these markers should display on top of each other.constbeaches=[["Bondi Beach",-33.890542,151.274856,4],["Coogee Beach",-33.923036,151.259052,5],["Cronulla Beach",-34.028249,151.157507,3],["Manly Beach",-33.80010128657071,151.28747820854187,2],["Maroubra Beach",-33.950198,151.259302,1],];functionsetMarkers(map){// Adds markers to the map.// Marker sizes are expressed as a Size of X,Y where the origin of the image// (0,0) is located in the top left of the image.// Origins, anchor positions and coordinates of the marker increase in the X// direction to the right and in the Y direction down.constimage={url:"https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png",// This marker is 20 pixels wide by 32 pixels high.size:newgoogle.maps.Size(20,32),// The origin for this image is (0, 0).origin:newgoogle.maps.Point(0,0),// The anchor for this image is the base of the flagpole at (0, 32).anchor:newgoogle.maps.Point(0,32),};// Shapes define the clickable region of the icon. The type defines an HTML// <area> element 'poly' which traces out a polygon as a series of X,Y points.// The final coordinate closes the poly by connecting to the first coordinate.constshape={coords:[1,1,1,20,18,20,18,1],type:"poly",};for(leti=0;i <beaches.length;i++){constbeach=beaches[i];newgoogle.maps.Marker({position:{lat:beach[1],lng:beach[2]},map,icon:image,shape:shape,title:beach[0],zIndex:beach[3],});}}window.initMap=initMap;
Try Sample
ConvertingMarkerImage objects to typeIcon
Until version 3.10 of the Maps JavaScript API, complex icons were defined asMarkerImage objects. TheIcon object literal was added in version 3.10, and replacesMarkerImage from version 3.11 onwards.Icon object literals support the same parameters asMarkerImage, allowing you to easily convert aMarkerImage to anIcon by removing the constructor, wrapping the previous parameters in{}'s, and adding the names of each parameter. For example:
varimage=newgoogle.maps.MarkerImage(place.icon,newgoogle.maps.Size(71,71),newgoogle.maps.Point(0,0),newgoogle.maps.Point(17,34),newgoogle.maps.Size(25,25));
becomes
varimage={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25)};
Optimize markers
Optimization enhances performance by rendering many markers as a single static element. This is useful in cases where a large number of markers is required. By default, the Maps JavaScript API will decide whether a marker will be optimized. When there is a large number of markers, the Maps JavaScript API will attempt to render markers with optimization. Not all Markers can be optimized; in some situations, the Maps JavaScript API may need to render Markers without optimization. Disable optimized rendering for animated GIFs or PNGs, or when each marker must be rendered as a separate DOM element. The following example shows creating an optimized marker:
varmarker=newgoogle.maps.Marker({position:myLatlng,title:"Hello World!",optimized:true});
Make a marker accessible
You can make a marker accessible by adding a click listener event, and settingoptimized tofalse. The click listener causes the marker to have button semantics, which can be accessed using keyboard navigation, screen readers, and so on. Use thetitle option to present accessible text for a marker.
In the following example, the first marker receives focus when tab is pressed; you can then use the arrow keys to move between markers. Press tab again to continue moving through the rest of the map controls. If a marker has an info window, you can open it by clicking the marker, or by pressing the enter key or space bar when the marker is selected. When the info window closes, focus will return to the associated marker.
TypeScript
// The following example creates five accessible and// focusable markers.functioninitMap():void{constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:12,center:{lat:34.84555,lng:-111.8035},});// Set LatLng and title text for the markers. The first marker (Boynton Pass)// receives the initial focus when tab is pressed. Use arrow keys to// move between markers; press tab again to cycle through the map controls.consttourStops:[google.maps.LatLngLiteral,string][]=[[{lat:34.8791806,lng:-111.8265049},"Boynton Pass"],[{lat:34.8559195,lng:-111.7988186},"Airport Mesa"],[{lat:34.832149,lng:-111.7695277},"Chapel of the Holy Cross"],[{lat:34.823736,lng:-111.8001857},"Red Rock Crossing"],[{lat:34.800326,lng:-111.7665047},"Bell Rock"],];// Create an info window to share between markers.constinfoWindow=newgoogle.maps.InfoWindow();// Create the markers.tourStops.forEach(([position,title],i)=>{constmarker=newgoogle.maps.Marker({position,map,title:`${i+1}.${title}`,label:`${i+1}`,optimized:false,});// Add a click listener for each marker, and set up the info window.marker.addListener("click",()=>{infoWindow.close();infoWindow.setContent(marker.getTitle());infoWindow.open(marker.getMap(),marker);});});}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// The following example creates five accessible and// focusable markers.functioninitMap(){constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:12,center:{lat:34.84555,lng:-111.8035},});// Set LatLng and title text for the markers. The first marker (Boynton Pass)// receives the initial focus when tab is pressed. Use arrow keys to// move between markers; press tab again to cycle through the map controls.consttourStops=[[{lat:34.8791806,lng:-111.8265049},"Boynton Pass"],[{lat:34.8559195,lng:-111.7988186},"Airport Mesa"],[{lat:34.832149,lng:-111.7695277},"Chapel of the Holy Cross"],[{lat:34.823736,lng:-111.8001857},"Red Rock Crossing"],[{lat:34.800326,lng:-111.7665047},"Bell Rock"],];// Create an info window to share between markers.constinfoWindow=newgoogle.maps.InfoWindow();// Create the markers.tourStops.forEach(([position,title],i)=>{constmarker=newgoogle.maps.Marker({position,map,title:`${i+1}.${title}`,label:`${i+1}`,optimized:false,});// Add a click listener for each marker, and set up the info window.marker.addListener("click",()=>{infoWindow.close();infoWindow.setContent(marker.getTitle());infoWindow.open(marker.getMap(),marker);});});}window.initMap=initMap;
Try Sample
Animate a marker
You can animate markers so that they exhibit dynamic movement in a variety of different circumstances. To specify the way a marker is animated, use the marker'sanimation property, of typegoogle.maps.Animation. The followingAnimation values are supported:
DROPindicates that the marker should drop from the top of the map to its final location when first placed on the map. Animation will cease once the marker comes to rest andanimationwill revert tonull. This type of animation is usually specified during creation of theMarker.BOUNCEindicates that the marker should bounce in place. A bouncing marker will continue bouncing until itsanimationproperty is explicitly set tonull.
You may initiate an animation on an existing marker by callingsetAnimation() on theMarker object.
TypeScript
// The following example creates a marker in Stockholm, Sweden using a DROP// animation. Clicking on the marker will toggle the animation between a BOUNCE// animation and no animation.letmarker:google.maps.Marker;functioninitMap():void{constmap=newgoogle.maps.Map(document.getElementById("map")asHTMLElement,{zoom:13,center:{lat:59.325,lng:18.07},});marker=newgoogle.maps.Marker({map,draggable:true,animation:google.maps.Animation.DROP,position:{lat:59.327,lng:18.067},});marker.addListener("click",toggleBounce);}functiontoggleBounce(){if(marker.getAnimation()!==null){marker.setAnimation(null);}else{marker.setAnimation(google.maps.Animation.BOUNCE);}}declareglobal{interfaceWindow{initMap:()=>void;}}window.initMap=initMap;
JavaScript
// The following example creates a marker in Stockholm, Sweden using a DROP// animation. Clicking on the marker will toggle the animation between a BOUNCE// animation and no animation.letmarker;functioninitMap(){constmap=newgoogle.maps.Map(document.getElementById("map"),{zoom:13,center:{lat:59.325,lng:18.07},});marker=newgoogle.maps.Marker({map,draggable:true,animation:google.maps.Animation.DROP,position:{lat:59.327,lng:18.067},});marker.addListener("click",toggleBounce);}functiontoggleBounce(){if(marker.getAnimation()!==null){marker.setAnimation(null);}else{marker.setAnimation(google.maps.Animation.BOUNCE);}}window.initMap=initMap;
Try Sample
If you have many markers, you might not want to drop them on the map all at once. You can make use ofsetTimeout() to space your markers' animations using a pattern like that shown below:
functiondrop(){for(vari=0;i<markerArray.length;i++){setTimeout(function(){addMarkerMethod();},i*200);}}
Make a marker draggable
To allow users to drag a marker to a different location on the map, setdraggable totrue in the marker options.
varmyLatlng=newgoogle.maps.LatLng(-25.363882,131.044922);varmapOptions={zoom:4,center:myLatlng}varmap=newgoogle.maps.Map(document.getElementById("map"),mapOptions);// Place a draggable marker on the mapvarmarker=newgoogle.maps.Marker({position:myLatlng,map:map,draggable:true,title:"Drag me!"});
Further Marker Customization
For a fully-customized marker, see thecustomized popup example.
For further extensions of the Marker class, marker clustering and management, and overlay customization, seeopen source libraries.
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.