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 type
Marker
.You can set a custom icon within the marker's constructor, or by
callingsetIcon()
on the marker. See more about
customizing the marker image.
Broadly speaking, markers are a type of overlay. For information on other types of overlay, see Drawing 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 an
info window
displaying custom information. You can allow users to move a marker on the
map by setting the marker'sdraggable
property to
true
.For more information about draggable markers, see
below.
Add a marker
The
google.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 aLatLng
identifying the initial location of the marker. One way of retrieving aLatLng
is by using the Geocoding service. -
map
(optional) specifies theMap
on 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:"HelloWorld!", }); } 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:"HelloWorld!", }); } 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 to
null
.
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 an image fileor vector-based iconto display instead of the default Google Maps pushpin icon. You can add text with a marker label,and use complex iconsto 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 /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 /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 using
SVG path notation,or use one of the predefined paths in
google.maps.SymbolPath.Theanchor
property is required in order for the marker to
render correctly when the zoom level changes. Learn more about
using 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.54712l6.563-6.609-1.406-1.406-5.1565.203-2.063-2.109-1.4061.406zM00q2.90604.9452.039t2.0394.945q01.453-0.7273.328t-1.7583.516-2.0393.070-1.7112.273l-0.750.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.9062.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.54712l6.563-6.609-1.406-1.406-5.1565.203-2.063-2.109-1.4061.406zM00q2.90604.9452.039t2.0394.945q01.453-0.7273.328t-1.7583.516-2.0393.070-1.7112.273l-0.750.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.9062.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 a
MarkerLabel
object that includes a string and other label properties.
When creating a marker, you can specify alabel
property in
the
MarkerOptions
object. Alternatively, you can callsetLabel()
on the
Marker
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 Alpha betical 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 Alpha betical 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 Alpha betical 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 Alpha betical 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 their
icon
properties to an object of type
Icon
.
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 the
anchor
where the icon's hotspot should be located (which is
based on the origin).
If you are using alabelwith a custom
marker, you can position the label with the
labelOrigin
property in the
Icon
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][]=[ ["BondiBeach",-33.890542,151.274856,4], ["CoogeeBeach",-33.923036,151.259052,5], ["CronullaBeach",-34.028249,151.157507,3], ["ManlyBeach",-33.80010128657071,151.28747820854187,2], ["MaroubraBeach",-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 /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=[ ["BondiBeach",-33.890542,151.274856,4], ["CoogeeBeach",-33.923036,151.259052,5], ["CronullaBeach",-34.028249,151.157507,3], ["ManlyBeach",-33.80010128657071,151.28747820854187,2], ["MaroubraBeach",-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 /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. The
Icon
object literal was added in version 3.10, and replaces
MarkerImage
from version 3.11 onwards.
Icon
object literals support the same parameters as
MarkerImage
,allowing you to easily convert a
MarkerImage
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 the
title
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},"BoyntonPass"], [{lat:34.8559195,lng:-111.7988186},"AirportMesa"], [{lat:34.832149,lng:-111.7695277},"ChapeloftheHolyCross"], [{lat:34.823736,lng:-111.8001857},"RedRockCrossing"], [{lat:34.800326,lng:-111.7665047},"BellRock"], ]; // 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},"BoyntonPass"], [{lat:34.8559195,lng:-111.7988186},"AirportMesa"], [{lat:34.832149,lng:-111.7695277},"ChapeloftheHolyCross"], [{lat:34.823736,lng:-111.8001857},"RedRockCrossing"], [{lat:34.800326,lng:-111.7665047},"BellRock"], ]; // 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 type
google.maps.Animation
.The following
Animation
values are supported:
-
DROP
indicates 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 andanimation
will revert tonull
.This type of animation is usually specified during creation of theMarker
. -
BOUNCE
indicates that the marker should bounce in place. A bouncing marker will continue bouncing until itsanimation
property is explicitly set tonull
.
You may initiate an animation on an existing marker by calling
setAnimation()
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;imarkerArray.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, set
draggable
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 map varmarker=newgoogle.maps.Marker({ position:myLatlng, map:map, draggable:true, title:"Drag me!" });
Further Marker Customization
For a fully-customized marker, see the customized popup example.
For further extensions of the Marker class, marker clustering and management, and overlay customization, see open source libraries.