How to Display Maps in Salesforce LWC (lightning-map vs Custom Mapbox Integration)

In plain words: Displaying maps in Salesforce Lightning Web Components (LWC) allows developers to visualize single or multiple geographical markers. You can implement this out of the box using Salesforce's native <lightning-map> base component, or build highly customized interfaces by loading third-party mapping engines like Mapbox GL JS through Static Resources.

Location intelligence helps sales reps, field service agents, and account managers visualize customer locations and route plans directly inside Salesforce records. Depending on your project requirements, you can choose between Salesforce's built-in map component (which requires zero external API keys) or a third-party mapping SDK for advanced custom rendering.

Prerequisites

• A Salesforce Developer Edition org, Scratch Org, or Sandbox environment.
• Salesforce CLI (sf) installed and authenticated.
• Basic knowledge of LWC lifecycle hooks (renderedCallback) and third-party library loading.

Approach 1: Using Salesforce Standard lightning-map (Recommended)

For most business applications, the standard lightning-map component is the best choice because it requires no external API keys, respects Salesforce security boundaries, and handles address geocoding automatically.

Template (standardMapDemo.html):

<template>
    <lightning-card title="Customer Locations (Standard Map)" icon-name="standard:address">
        <div class="slds-p-around_medium">
            <lightning-map
                map-markers={mapMarkers}
                zoom-level={zoomLevel}
                list-view="visible">
            </lightning-map>
        </div>
    </lightning-card>
</template>

JavaScript Controller (standardMapDemo.js):

import { LightningElement } from 'lwc';

export default class StandardMapDemo extends LightningElement {
    zoomLevel = 14;

    mapMarkers = [
        {
            location: {
                Street: '1 Market St',
                City: 'San Francisco',
                State: 'CA',
                PostalCode: '94105',
                Country: 'USA'
            },
            value: 'SF_HQ',
            title: 'Salesforce Global HQ',
            description: 'Salesforce Tower - San Francisco',
            icon: 'standard:account'
        },
        {
            location: {
                Latitude: 37.7897,
                Longitude: -122.4011
            },
            value: 'SF_OFFICE_2',
            title: 'Regional Office',
            description: 'Coordinates-based Marker',
            icon: 'standard:location'
        }
    ];
}

Approach 2: Custom Mapping with Mapbox GL JS

When you need custom raster tiles, 3D building rendering, or custom layer clustering, you can load Mapbox GL JS as a Static Resource.

Static Resource Setup:

• Download Mapbox GL JS (mapbox-gl.js and mapbox-gl.css).
• Upload the ZIP file or JS/CSS files to Setup > Static Resources under the name mapboxgl.
• Add https://api.mapbox.com and your tile domains to Setup > Security > Remote Site Settings and CSP Trusted Sites.

HTML Template (customMapboxDemo.html):

<template>
    <lightning-card title="Custom Mapbox GL Integration" icon-name="utility:world">
        <div class="slds-p-around_medium">
            <div class="map-container">
                <div class="map" lwc:dom="manual"></div>
            </div>
        </div>
    </lightning-card>
</template>

CSS Styling (customMapboxDemo.css):

.map-container {
    height: 420px;
    width: 100%;
    border-radius: 6px;
    overflow: hidden;
    border: 1px solid #dddbda;
}

.map {
    height: 100%;
    width: 100%;
}

JavaScript Controller (customMapboxDemo.js):

import { LightningElement } from 'lwc';
import { loadScript, loadStyle } from 'lightning/platformResourceLoader';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import MAPBOX_RESOURCE from '@salesforce/resourceUrl/mapboxgl';

export default class CustomMapboxDemo extends LightningElement {
    map;
    isMapboxInitialized = false;

    renderedCallback() {
        if (this.isMapboxInitialized) {
            return;
        }
        this.isMapboxInitialized = true;

        Promise.all([
            loadScript(this, MAPBOX_RESOURCE + '/mapbox-gl.js'),
            loadStyle(this, MAPBOX_RESOURCE + '/mapbox-gl.css')
        ])
        .then(() => {
            this.initializeMap();
        })
        .catch(error => {
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Mapbox Load Error',
                    message: error?.message || 'Failed to load mapping engine resources.',
                    variant: 'error'
                })
            );
        });
    }

    initializeMap() {
        const container = this.template.querySelector('.map');
        
        // Replace with your public Mapbox access token
        window.mapboxgl.accessToken = 'YOUR_MAPBOX_PUBLIC_TOKEN';

        this.map = new window.mapboxgl.Map({
            container: container,
            style: 'mapbox://styles/mapbox/streets-v11',
            center: [-122.4011, 37.7897], // [Longitude, Latitude]
            zoom: 12
        });

        // Add standard navigation controls (Zoom in/out)
        this.map.addControl(new window.mapboxgl.NavigationControl());
    }
}

Warning Trap: Third-party libraries that mutate DOM elements directly (such as Mapbox inserting canvas elements) require the lwc:dom="manual" directive on the target container element. If you omit this directive, the LWC engine will block manual DOM alterations to protect Shadow DOM boundaries.

360 Architecture Summary:

• Standard <lightning-map>: No external subscriptions, free native geocoding by address fields, built-in SLDS markers, and native mobile responsiveness.
• Third-Party Libraries (Mapbox / Leaflet): Required when custom vector tiles, heatmaps, polygon boundary drawing, or specialized GIS layers are needed.
• CSP Restrictions: External tile endpoints must always be added to CSP Trusted Sites in Salesforce Setup.
• Coordinate Ordering: Notice that Mapbox coordinates use [Longitude, Latitude], whereas Google and standard Salesforce APIs use {Latitude, Longitude}.

Step 3: Configure Metadata and Deploy

Update customMapboxDemo.js-meta.xml to expose the component to Lightning App Builder:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__RecordPage</target>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

Deployment & Testing Routine:

# Deploy the component bundle
sf project deploy start

# Open target org in browser
sf org open

• Navigate to Setup > Lightning App Builder.
• Drag the mapping component onto your Record or App page, save, and activate.
• Confirm that map tiles and markers render correctly on both desktop and mobile viewports.

Core Takeaway: Use the native lightning-map component for fast, out-of-the-box address visualization without API keys. For complex GIS layers or custom vector tiles, load Mapbox GL JS via platformResourceLoader using lwc:dom="manual".