Map (Beta)

lightning:map

Displays a map of one or more locations. This component requires API version 44.0 and later.

For Aura components only. For LWC development, use lightning-map.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App

lightning:map is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer’s sole discretion.

Note

A lightning:map component securely displays a map of one or more locations, using geocoding data and mapping imagery from Google Maps. The map image is shown in a container, with an optional list of the locations. The list is visible by default when there are multiple locations specified. When you select a location title in the list, its map marker is activated. The list is shown beside or below the map, depending on the width of the container.

lightning:map loads content from the Salesforce domain maps.a.forceusercontent.com in an iframe. You must allow maps.a.forceusercontent.com if you want to use this component in your own domain and you use the Content Security Policy frame-src directive, such as in Experience Builder sites or Lightning Out. For more information, see Content Security Policy in Experience Builder sites.

This component implements styling from map in the Lightning Design System.

Pass the locations to be displayed via the component’s mapMarkers property.

The following example loads the map markers during initialization.

1<aura:component>
2  <aura:attribute name="mapMarkers" type="Object[]" />
3  <aura:handler name="init" value="{! this }" action="{! c.init }" />
4
5  <lightning:map mapMarkers="{! v.mapMarkers }" />
6</aura:component>

Define the markers in your client-side controller. This example uses a single marker.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          Street: "415 Mission St",
7          City: "San Francisco",
8          State: "CA",
9        },
10
11        title: "Salesforce Tower",
12        description: "San Francisco's tallest building",
13      },
14    ]);
15  },
16});

mapMarkers is an array of markers that indicate location. A marker contains

Location Information: A coordinate pair of latitude and longitude, or an address composed of address elements to be geocoded.
Descriptive Information: Optional title, description, and an icon. These are relevant to the marker but not specifically related to location.

Marker Properties

Use the following marker properties to customize the map display.

Property	Type	Description
`location`	object	Address elements (City, Country, PostalCode, State, and Street) to be geocoded, or a set of latitude and longitude coordinates. If you specify address elements and coordinates for one location, the map uses the coordinates. To support reliable geocoding of addresses, if you specify Street, you must also specify at least one of City, Country, PostalCode or State.
`title`	string	Title text for the location, displayed in the location list and in the info window when you click a marker. HTML tags are not supported and are displayed as unescaped markup.
`description`	string	Text describing the location, displayed in the info window when you click a marker or location title. A subset of HTML tags is supported. See Using HTML Tags in Descriptions.
`icon`	string	The icon that’s displayed next to the location title in the list. Only Lightning Design System icons are supported. Custom icons are currently not supported in the location list. The default is standard:location. For more information, see Displaying Multiple Addresses and a Title.
`value`	string	An optional unique identifier for a marker. When a marker is selected, its value is assigned to the `selectedMarkerValue` attribute.
`type`	string	A type of shape to use instead of the default map marker. Accepted values are `Circle`, `Rectangle`, and `Polygon`. See Marking Locations with Shapes.
`mapIcon`	object	A custom SVG icon to use instead of the default map marker. See Marking Locations with Custom Icons.

Using HTML Tags in Descriptions

HTML tags are supported for use with the description property. The supported HTML tags are b, br, del, em, h1, h2, h3, h4, h5, h6, i, ins, mark, p, small, strong, sub, and sup. Other HTML tags you pass to description are sanitized and removed.

This example formats some words in a marker description to make them bold and italicized.

1mapMarkers = [
2  {
3    location: {
4      Street: "1 Market St",
5      City: "San Francisco",
6      Country: "USA",
7    },
8    title: "The Landmark Building",
9    description: "Historic <b>11-story</b> building completed in <i>1916</i>",
10  },
11];

Displaying a Single Marker

Here’s an example of a marker that uses address elements.

1[{
2    location: {
3        City: 'San Francisco',
4        Country: 'USA',
5        PostalCode: '94105',
6        State: 'CA',
7        Street: 'The Landmark @ One Market, Suite 300'
8    },
9    title: 'The Landmark Building',
10    description: 'The Landmark is considered to be one of the city's most architecturally distinct and historic properties',
11    icon: 'standard:account',
12    value: 'location001'
13}]

Here’s an example of a marker that uses coordinates for latitude and longitude.

1{
2    Latitude: '37.790197',
3    Longitude: '-122.396879'
4}

For each map marker in the array of map markers, provide either latitude and longitude coordinates or address elements to be geocoded. If you specify both in a single marker, latitude and longitude get precedence.

Displaying Multiple Addresses and a Title

When you specify multiple markers in an array, the lightning:map component renders a list of tiles with location titles and addresses, with a heading displayed above the list. Each location tile contains an icon, a title, and an address.

Specify the markersTitle attribute to display a custom heading for your locations. If you don’t pass this attribute, the heading is “Markers(n)” where n is the number of markers you provide.

1<aura:component>
2  <aura:attribute name="mapMarkers" type="Object[]" />
3  <aura:attribute name="selectedMarkerValue" type="String" default="SF1" />
4
5  <aura:handler name="init" value="{! this }" action="{! c.init }" />
6
7  <lightning:map
8    mapMarkers="{!v.mapMarkers}"
9    markersTitle="Lunch Gems"
10    onmarkerselect="{!c.handleMarkerSelect}"
11    selectedMarkerValue="{!v.selectedMarkerValue}"
12  />
13</aura:component>

To select a marker on load, use the selectedMarkerValue attribute. Retrieve the selected marker using the onmarkerselect handler.

To customize each location tile, you can specify the optional icon, title, and description properties for each address. The lightning:map component displays the icon next to the address. The description is displayed in an info window when the user clicks the marker.

Get the selected marker using event.getParam("selectedMarkerValue");

1({
2  init: function (cmp, event, helper) {
3    mapMarkers = [
4      {
5        location: {
6          // Location Information
7          City: "San Francisco",
8          Country: "USA",
9          PostalCode: "94105",
10          State: "CA",
11          Street: "50 Fremont St",
12        },
13
14        // For onmarkerselect
15        value: "SF1",
16
17        // Extra info for tile in list and info window
18        icon: "standard:account",
19        title: "Julies Kitchen", // e.g. Account.Name
20        description: "This is a long description",
21      },
22      {
23        location: {
24          // Location Information
25          City: "San Francisco",
26          Country: "USA",
27          PostalCode: "94105",
28          State: "CA",
29          Street: "30 Fremont St.",
30        },
31
32        // For onmarkerselect
33        value: "SF2",
34
35        // Extra info for tile in list
36        icon: "standard:account",
37        title: "Tender Greens", // e.g. Account.Name
38      },
39    ];
40
41    cmp.set("v.mapMarkers", mapMarkers);
42  },
43
44  handleMarkerSelect: function (cmp, event, helper) {
45    var marker = event.getParam("selectedMarkerValue");
46  },
47});

Displaying or Hiding the List of Locations

By default, the list of locations is hidden when you pass in a single marker and displayed when you pass in multiple markers. To hide the list of locations for multiple markers, set listView="hidden". To display the list of locations for a single marker, set listView="visible".

The example for specifying zoomLevel also uses listView.

Specifying Zoom Level

If you don’t specify the zoomLevel attribute, the lightning:map component calculates a zoom level to accommodate the markers in your map.

To specify a particular zoom level, set zoomLevel to a value corresponding to a Google Maps API zoom level. Currently, Google Maps API supports zoom levels from 1 to 22 in desktop browsers, and from 1 to 20 on mobile. For more information, see Zoom Levels in the Google Maps API documentation.

Here’s an example that uses zoomLevel and listView.

1<aura:component>
2  <!-- attributes -->
3  <aura:attribute name="mapMarkers" type="Object" />
4  <aura:attribute name="markersTitle" type="String" />
5  <aura:attribute name="listView" type="String" />
6  <aura:attribute name="zoomLevel" type="Integer" />
7
8  <!-- handlers-->
9  <aura:handler name="init" value="{! this }" action="{! c.init }" />
10
11  <!-- the map component -->
12  <lightning:map
13    mapMarkers="{! v.mapMarkers }"
14    markersTitle="{!v.markersTitle}"
15    listView="{!v.listView}"
16    zoomLevel="{!v.zoomLevel}"
17  />
18</aura:component>

The client-side controller sets the markers, zoom level, and list view visibility.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          Street: "1000 5th Ave",
7          City: "New York",
8          State: "NY",
9        },
10
11        title: "Metropolitan Museum of Art",
12        description:
13          "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
14      },
15    ]);
16
17    cmp.set("v.zoomLevel", 11);
18    cmp.set("v.markersTitle", "The Met");
19    cmp.set("v.listView", "visible");
20  },
21});

Centering the Map

When a map uses multiple map markers, the component centers the map on a location near the center of the markers by calculating the geometric mean.

Use the center attribute to specify a different location for the map’s center. You can specify latitude and longitude, or at least one of the address elements: Country, State, City, and PostalCode. Street is optional. The center location format is the same as the mapMarkers location format. However, you can’t specify a title, icon, or description for the center.

Here’s an example that centers the map using latitude and longitude.

1<aura:component>
2  <!-- attributes -->
3  <aura:attribute name="mapMarkers" type="Object" />
4  <aura:attribute name="markersTitle" type="String" />
5  <aura:attribute name="center" type="Object" />
6
7  <!-- handlers-->
8  <aura:handler name="init" value="{! this }" action="{! c.init }" />
9
10  <!-- the map component -->
11  <lightning:map
12    mapMarkers="{! v.mapMarkers }"
13    markersTitle="{!v.markersTitle}"
14    center="{!v.center}"
15  />
16</aura:component>

The client-side controller sets the attribute values.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          Street: "1000 5th Ave",
7          City: "New York",
8          State: "NY",
9        },
10
11        title: "Metropolitan Museum of Art",
12        description:
13          "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
14      },
15      {
16        location: {
17          Street: "11 W 53rd St",
18          City: "New York",
19          State: "NY",
20        },
21
22        title: "Museum of Modern Art (MoMA)",
23        description: "Thought-provoking modern and contemporary art.",
24      },
25      {
26        location: {
27          Street: "1071 5th Ave",
28          City: "New York",
29          State: "NY",
30        },
31
32        title: "Guggenheim Museum",
33        description:
34          "World-renowned collection of modern and contemporary art.",
35      },
36    ]);
37
38    cmp.set("v.markersTitle", "Coordinates for Centering");
39    cmp.set("v.center", {
40      location: {
41        Latitude: "40.7831856",
42        Longitude: "-73.9675653",
43      },
44    });
45  },
46});

The same map could use address elements to center:

1cmp.set("v.center", {
2  location: { Street: "170 Central Park West", PostalCode: "10024" },
3});

The footer displays a link for opening a location in Google Maps in a new window. By default, the first marker location opens. When viewing a map with multiple locations, select a location from the list before clicking the link to open that location in Google Maps. The external Google map image shows a marker labeled with the location information that’s specified for the marker in lightning:map. The title and description is not included.

To display the footer, specify the showFooter="true" attribute.

1<lightning:map
2  mapMarkers="{! v.mapMarkers }"
3  markersTitle="{!v.markersTitle}"
4  showFooter="true"
5/>

Setting Map Controls

lightning:map enables you to specify which map controls to allow. Set the options attribute to enable or disable map controls using the following boolean properties.

Property	Default Value	Description
`draggable`	true	Enables dragging to pan the map with the mouse. Set to false to prevent dragging. This property affects the map only. Markers aren’t draggable.
`zoomControl`	true	Shows the +/- zoom controls on the bottom of the map. Set to false to remove the controls and prevent zooming.
`scrollwheel`	true	Permits zooming with the mouse wheel. Set to false to disable zooming with the mouse wheel when zooming is enabled. If `zoomControl` is false or `disableDefaultUI` is true, the `scrollwheel` setting has no effect because these settings disable zooming.
`disableDefaultUI`	false	Set to true to remove Map/Satellite and +/- zoom buttons. The satellite view and zooming are disabled. Mouse scrolling and dragging is not affected by `disableDefaultUI`.
`disableDoubleClickZoom`	false	Set to true to disable zooming with a mouse double-click when zooming is enabled.

Zooming behavior is influenced by all the properties except draggable.

To prevent all zooming, set zoomControl: false
To prevent all zooming and also remove the Map/Satellite buttons, set disableDefaultUI: true
To allow zooming, but prevent the scroll wheel from activating zoom, set scrollwheel: false
To allow zooming, but prevent a double-click from activating zoom, set disableDoubleClickZoom: true

This example disables dragging and also disables the default UI, which removes the zoom capability and Map/Satellite button. The result is a static map.

1<aura:component>
2  <!-- attributes -->
3  <aura:attribute name="mapMarkers" type="Object" />
4  <aura:attribute name="mapOptions" type="Object" />
5
6  <!-- handlers-->
7  <aura:handler name="init" value="{! this }" action="{! c.init }" />
8
9  <!-- the map component -->
10  <lightning:map
11    mapMarkers="{!v.mapMarkers}"
12    options="{!v.mapOptions}"
13    zoomLevel="14"
14  />
15</aura:component>

The client-side controller sets the properties for options.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          Street: "1000 5th Ave",
7          City: "New York",
8          State: "NY",
9        },
10
11        title: "Metropolitan Museum of Art",
12        description:
13          "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
14      },
15    ]);
16
17    cmp.set("v.mapOptions", {
18      draggable: false,
19      disableDefaultUI: true,
20    });
21  },
22});

Marking Locations with Shapes

lightning:map enables you to customize your maps to use different indicators for locations instead of the default Google Maps markers.

The mapMarkers attribute supports the type property to define colored shapes to mark a location. Available type values are Circle, Rectangle, and Polygon. The values are case-sensitive.

The type property works with the following properties to define a shape’s appearance.

`type` Value	Property	Property Type	Description
`Circle`	`radius`	number	The number in meters for the radius of the circle. This value represents the Earth’s surface included in the circle around the location.
`Rectangle`	`bounds`	object	Uses `north` and `south` latitude values and `east` and `west` longitude values to specify the corners of the rectangle.
`Polygon`	`paths`	object	Defines a set of `lat` and `lng` properties for the latitude and longitude coordinates of the polygon’s shape.
All	`strokeColor`	string	Hexadecimal color code or CSS3 color name for the stroke, which creates the edge of the shape.
	`strokeOpacity`	number	The degree of transparency of the stroke. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.
	`strokeWeight`	number	The stroke width in pixels.
	`fillColor`	string	Hexadecimal color code or CSS3 color name to fill the shape.
	`fillOpacity`	number	The degree of transparency of the fill for the shape. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.

Mark a Location with a Circle

This example creates a yellow circle to mark the location.

1<aura:component>
2  <!-- attributes -->
3  <aura:attribute name="mapMarkers" type="Object" />
4  <!-- handlers-->
5  <aura:handler name="init" value="{! this }" action="{! c.init }" />
6
7  <!-- the map component -->
8  <lightning:map mapMarkers="{!v.mapMarkers}" zoomLevel="15" />
9</aura:component>

The mapMarkers object defines the location and the type. The properties specified after type define the circle as having a 200 meter radius, and a yellow color #FFF000 for both the stroke edge and fill, with the edge more opaque than the fill.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          City: "San Francisco",
7          Country: "USA",
8          PostalCode: "94105",
9          State: "CA",
10          Street: "50 Fremont St",
11        },
12        type: "Circle",
13        radius: 200,
14        strokeColor: "#FFF000",
15        strokeOpacity: 0.8,
16        strokeWeight: 2,
17        fillColor: "#FFF000",
18        fillOpacity: 0.35,
19      },
20    ]);
21  },
22});

Mark a Location with a Rectangle

This example shows the JavaScript for defining a rectangle shape for a location.

The mapMarkers object sets the type to Rectangle. The bounds property defines the four coordinates of the rectangle for the location. Other properties define the characteristics of the stroke and fill.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          City: "San Francisco",
7          Country: "USA",
8          PostalCode: "94105",
9          State: "CA",
10          Street: "500 Howard St",
11        },
12        type: "Rectangle",
13        bounds: {
14          north: 37.788,
15          south: 37.774,
16          east: -122.395,
17          west: -122.412,
18        },
19        strokeColor: "#0b5411",
20        strokeOpacity: 0.8,
21        strokeWeight: 2,
22        fillColor: "#0b5411",
23        fillOpacity: 0.35,
24      },
25    ]);
26  },
27});

Mark a Location with a Polygon

This example sets the type to Polygon and draws a pink polygon with a black outline. The polygon’s segments are defined in the paths property using coordinates specified by the lat and lng properties.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          City: "San Francisco",
7          Country: "USA",
8          PostalCode: "94105",
9          State: "CA",
10          Street: "425 Mission St",
11        },
12        type: "Polygon",
13        paths: [
14          { lat: 37.78806990305951, lng: -122.39873856028704 },
15          { lat: 37.790689809711886, lng: -122.39540189227252 },
16          { lat: 37.79036762555352, lng: -122.39495128115801 },
17          { lat: 37.787569651422224, lng: -122.39842742404132 },
18          { lat: 37.7879172842749, lng: -122.39886730631976 },
19          { lat: 37.7880699030595, lng: -122.39873856028704 },
20        ],
21        strokeColor: "black",
22        strokeOpacity: 0.35,
23        strokeWeight: 2,
24        fillColor: "pink",
25        fillOpacity: 0.35,
26      },
27    ]);
28  },
29});

Marking Locations with Custom Icons

Use the mapIcon property with the mapMarkers attribute to specify an SVG icon image in place of the Google Maps marker.

Use either type or mapIcon to customize a given location. You can’t use both for one location.

The mapIcon property works with the following properties to define the icon’s appearance.

Property	Type	Description
`path`	string	SVG path notation to add a vector-based symbol as the icon for a marker.
`anchor`	Point	Coordinates used to align the marker to the map coordinates when the zoom level changes. The default anchor is (0,0) which can lead to the marker moving when you zoom out. Set the anchor coordinates to account for the width and height of the icon. For example, set the x value equal to half the image width and the y value equal to half the image height.
`scale`	number	The amount by which the marker icon is scaled in size. The default value is 1. The marker icon size is multiplied by the scale value to produce the actual output size of the marker in pixels.
`strokeColor`	string	Hexadecimal color code or CSS3 color name for the stroke, which creates the edge of the custom icon.
`strokeOpacity`	number	The degree of transparency of the stroke. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.
`strokeWeight`	number	The stroke width in pixels. The default is 1.
`fillColor`	string	Hexadecimal color code or CSS3 color name to fill the icon.
`fillOpacity`	number	The degree of transparency of the fill for the icon. The value is between 0.0 and 1.0, where 0.0 is transparent and 1.0 is opaque.

This example creates a gold star without an outline as the marker. The listView is made visible to show that a location with a custom marker is displayed in the list of markers.

1<aura:component>
2  <!-- attributes -->
3  <aura:attribute name="mapMarkers" type="Object" />
4
5  <!-- handlers-->
6  <aura:handler name="init" value="{! this }" action="{! c.init }" />
7
8  <!-- the map component -->
9  <lightning:map
10    mapMarkers="{! v.mapMarkers }"
11    zoomLevel="15"
12    listView="visible"
13  />
14</aura:component>

The path creates a star that’s 245px x 230px. Use an SVG editor to determine the image size, which helps determine the anchor coordinates needed. See MDN for a list of SVG tools.

The anchor property sets the x coordinate to 122.5 which is half the width of the image, and sets the y coordinate to 115 which is half the height of the image. For more information about the anchor property, see Markers with vector-based icons in the Google Maps Platform documentation.

The scale property sets the star to display at a comfortable size for the map viewed on a desktop.

1({
2  init: function (cmp, event, helper) {
3    cmp.set("v.mapMarkers", [
4      {
5        location: {
6          City: "San Francisco",
7          Country: "USA",
8          PostalCode: "94105",
9          State: "CA",
10          Street: "415 Mission St",
11        },
12        mapIcon: {
13          path:
14            "M 125,5 155,90 245,90 175,145 200,230 125,180 50,230 75,145 5,90 95,90 z",
15          fillColor: "gold",
16          fillOpacity: 0.8,
17          strokeWeight: 0,
18          scale: 0.1,
19          anchor: { x: 122.5, y: 115 },
20        },
21      },
22    ]);
23  },
24});

Geocoding Addresses

The lightning:map component relies on data from Google for geocoding and mapping imagery. Inaccuracies or geocoding errors in the data can’t be fixed by Salesforce.

You can specify a maximum of 10 geocoded address lookups per map. Lookups for both the mapMarkers and center attributes count toward this limit. To display more markers, provide location values using a pair of latitude and longitude coordinates, which don’t require geocoding. Address locations that exceed the geocoding limit are ignored.

We recommend limiting your map to 100 locations in total. For example, if you provide map markers for 5 geocoded addresses, you can provide up to 95 additional markers using latitude and longitude.

All latitude and longitude values must be valid. If you pass in an invalid latitude or longitude, the markers aren’t plotted on the map. Latitude values fall within -90 and 90, and longitude values fall within -180 and 180.

Additionally, consider the following:

If you specify an address, you must provide at least one of the following values: City, PostalCode, State or Country.
If you pass in both an address and a latitude and longitude, the map plots the marker according to the latitude and longitude values.
If a marker in the mapMarkers array is invalid, no markers are plotted on the map.

Usage Considerations

lightning:map uses the Google Maps Platform and is bound to its terms of service. The use of Google Maps Platform is prohibited in specific territories based on IP addresses. For more information, see Google Maps Platform Prohibited Territories. lightning:map is not supported in these territories and does not load correctly when accessed from the IP addresses associated with these territories. Users in these territories can continue to use Google Maps directly as detailed at Google Maps Platform Coverage Details.

Attributes

Name	Description	Type	Default
body	The body of the component. In markup, this is everything in the body of the tag.	Aura.Component[]
center	A location to use as the map's center. If center is not specified, the map centers automatically.	Object
class	A CSS class for the outer element, in addition to the component's base classes.	String
listView	Displays or hides the list of locations. Valid values are visible, hidden, or auto. This value defaults to auto, which shows the list only when multiple markers are present. Passing in an invalid value hides the list view.	String	auto
mapMarkers	Array containing one or more objects with the address or coordinates to be displayed.	Object[]
markersTitle	Provides the heading title for the markers when the map uses multiple markers. The title is displayed as a header for the list of clickable addresses.	String
onmarkerselect	Action fired when a marker is selected. Select a marker by clicking it on the map or in the list of locations.	Aura.Action
selectedMarkerValue	Provides the value of the currently selected marker. Returns undefined if you don’t pass a value to mapMarkers.	String
showFooter	Shows footer with 'Open in Google Maps' link that opens an external window to display the selected marker location in Google Maps. Default value is false.	Boolean	false
title	Displays tooltip text when the mouse moves over the element.	String
zoomLevel	Corresponds to zoom levels defined in Google Maps API. If not specified, the map component automatically chooses an appropriate zoom level to show all markers with comfortable margins.	Integer