Map (Beta)

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.

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

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.

Use the following marker properties to customize the map display.

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.

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

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

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.

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.

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");

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.

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.

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

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.

The client-side controller sets the attribute values.

The same map could use address elements to center:

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.

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.

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.

The client-side controller sets the properties for options.

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.

This example creates a yellow circle to mark the location.

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.

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.

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.

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.

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.

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.

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.

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.