Map (Beta)

A lightning-map component shows 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 multiple locations are 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. Allow maps.a.forceusercontent.com if you 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.

Pass the locations to the component’s map-markers property.

For example:

1<template>
2    <lightning-map map-markers={mapMarkers}> </lightning-map>
3</template>

lightning-map implements the map blueprint in the Salesforce Lightning Design System (SLDS). The map adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

map-markers is an array of markers that indicate location.

A marker contains map data:

• 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 items are relevant to the marker but not specifically related to location.

Use these marker properties to customize the map.

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];

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

1import { LightningElement } from "lwc";
2
3export default class LightningMapExample extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        City: "San Francisco",
8        Country: "USA",
9        PostalCode: "94105",
10        State: "CA",
11        Street: "The Landmark @ One Market, Suite 300",
12      },
13      value: "location001",
14      title: "The Landmark Building",
15      description:
16        "The Landmark is considered to be one of the city's most architecturally distinct and historic properties", //escape the apostrophe in the string using '
17      icon: "standard:account",
18    },
19  ];
20}

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

1import { LightningElement } from "lwc";
2
3export default class LightningMapExample extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        Latitude: "37.790197",
8        Longitude: "-122.396879",
9      },
10    },
11  ];
12}

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 that’s placed above the list. Each location tile contains an icon, a title, and an address.

Specify the markers-title attribute for 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<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        markers-title="Lunch Gems"
5        onmarkerselect={handleMarkerSelect}
6        selected-marker-value={selectedMarkerValue}
7    >
8    </lightning-map>
9</template>

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

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

Get the selected marker using the event.target.selectedMarkerValue property.

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

By default, the list of locations is hidden when you pass in a single marker and shown when you pass in multiple markers. To hide the list of locations for multiple markers, set list-view="hidden". To show the list of locations for a single marker, set list-view="visible".

If you specify a type to show a shape at a location, the list view doesn’t show an entry for the location. See Mark Locations with Shapes.

The example for specifying zoom-level also uses list-view.

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

To specify a particular zoom level, set zoom-level 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 zoom-level and list-view attributes.

1<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        zoom-level={zoomLevel}
5        list-view={listView}
6    >
7    </lightning-map>
8</template>

The component’s JavaScript sets the markers, zoom level, and list view visibility.

1import { LightningElement } from "lwc";
2
3export default class LightningMapExample extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        Street: "1000 5th Ave",
8        City: "New York",
9        State: "NY",
10      },
11
12      title: "Museum of Fine Arts",
13      description:
14        "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
15    },
16  ];
17  zoomLevel = 15;
18  listView = "visible";
19}

When you have 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 map-markers 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<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        markers-title={markersTitle}
5        center={center}
6    >
7    </lightning-map>
8</template>

The markers and the center are set in JavaScript.

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

The same map could use address elements to center:

1center = {
2  location: { Street: "170 Central Park West", PostalCode: "10024" },
3};

The footer shows a link for opening the map in Google Maps in a new window or tab. 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 aren’t included.

To show the footer, specify the show-footer attribute.

1<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        markers-title={markersTitle}
5        show-footer
6    >
7    </lightning-map>
8</template>

lightning-map enables you to specify which map controls to allow. Set the options attribute to enable or disable map controls using these 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.

1<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        options={mapOptions}
5        zoom-level="14"
6    ></lightning-map>
7</template>

The values of the options attribute are set in an object of boolean values in JavaScript.

1import { LightningElement } from "lwc";
2
3export default class LightningExampleMapControls extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        Street: "1000 5th Ave",
8        City: "New York",
9        State: "NY",
10      },
11
12      title: "Metropolitan Museum of Art",
13      description:
14        "A grand setting for one of the greatest collections of art, from ancient to contemporary.",
15    },
16  ];
17  mapOptions = {
18    draggable: false,
19    disableDefaultUI: true,
20  };
21}

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

The map-markers 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 these properties to define a shape’s appearance.

This example creates a yellow circle to mark the location.

1<template>
2    <lightning-map map-markers={mapMarkers} zoom-level="15"></lightning-map>
3</template>

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.

1import { LightningElement } from "lwc";
2
3export default class MapCircleShape extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        City: "San Francisco",
8        Country: "USA",
9        PostalCode: "94105",
10        State: "CA",
11        Street: "50 Fremont St",
12      },
13      type: "Circle",
14      radius: 200,
15      strokeColor: "#FFF000",
16      strokeOpacity: 0.8,
17      strokeWeight: 2,
18      fillColor: "#FFF000",
19      fillOpacity: 0.35,
20    },
21  ];
22}

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 coordinates of the rectangle for the location. Other properties define the characteristics of the stroke and fill.

1import { LightningElement } from "lwc";
2
3export default class MapRectangleShapeExample extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        City: "San Francisco",
8        Country: "USA",
9        PostalCode: "94105",
10        State: "CA",
11        Street: "500 Howard St",
12      },
13      type: "Rectangle",
14      bounds: {
15        north: 37.788,
16        south: 37.774,
17        east: -122.395,
18        west: -122.412,
19      },
20      strokeColor: "#0b5411",
21      strokeOpacity: 0.8,
22      strokeWeight: 2,
23      fillColor: "#0b5411",
24      fillOpacity: 0.35,
25    },
26  ];
27}

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.

1import { LightningElement } from "lwc";
2
3export default class MapPolygonShape extends LightningElement {
4  mapMarkers = [
5    {
6      location: {
7        City: "San Francisco",
8        Country: "USA",
9        PostalCode: "94105",
10        State: "CA",
11        Street: "425 Mission St",
12      },
13      type: "Polygon",
14      paths: [
15        { lat: 37.78806990305951, lng: -122.39873856028704 },
16        { lat: 37.790689809711886, lng: -122.39540189227252 },
17        { lat: 37.79036762555352, lng: -122.39495128115801 },
18        { lat: 37.787569651422224, lng: -122.39842742404132 },
19        { lat: 37.7879172842749, lng: -122.39886730631976 },
20        { lat: 37.7880699030595, lng: -122.39873856028704 },
21      ],
22      strokeColor: "black",
23      strokeOpacity: 0.35,
24      strokeWeight: 2,
25      fillColor: "pink",
26      fillOpacity: 0.35,
27    },
28  ];
29}

Pass the mapIcon property to the map-markers 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 list-view is made visible to show that a location with a custom marker is displayed in the list of markers.

1<template>
2    <lightning-map
3        map-markers={mapMarkers}
4        zoom-level="15"
5        list-view="visible"
6    ></lightning-map>
7</template>

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.

1import { LightningElement } from 'lwc';
2
3export default class MapCustomIconExample extends LightningElement {
4    mapMarkers = [
5        {
6            location: {
7                City: 'San Francisco',
8                Country: 'USA',
9                PostalCode: '94105',
10                State: 'CA',
11                Street: '415 Mission St',
12            },
13            mapIcon: {
14            path: '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: .8,
17            strokeWeight: 0,
18            scale: .10,
19            anchor: {x: 122.5, y: 115}
20            },
21        ];
22    }
23}

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 map-markers and center attributes count toward the limit of 10 geocoded addresses. To show 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 extra 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.

Also consider these guidelines:

• If you specify an address, you must provide at least one of these 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 map-markers 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.

markerselect

The event fired when a marker is selected. Select a marker by clicking it on the map or in the list of locations. The value of the selected marker is available on the selected-marker-value attribute on the component.

The markerselect event returns this parameter.

The event properties are as follows.