Map

avonni-dd-map

The Avonni Data Driven Map displays records as markers on a Google Map.

Overview

Map is a data-driven Lightning Web Component that displays records as markers on a Google Map, with an optional list of clickable locations below the map.

The component works in two modes. In query mode, you provide a query and a mapping; the component runs the query, maps each returned record to a marker, and places it on the map using the record's address or coordinates. In static mode, you provide a fixed items array and the component renders those markers directly, ignoring query and mapping.

Use Cases

• Account territory views: Plot every account in a region from its billing address.
• Store and office locators: Show a fixed set of locations from a static items array.
• Service dispatch: Map open cases or work orders by their geolocation.
• Event venues: Display sessions or venues with a heading list below the map.
• Asset tracking: Visualize installed assets or equipment by coordinates.
• Lead clustering: Surface prospects geographically to plan field visits.

---

Use Case Examples

Example 1: Query mode

Scenario: Plot every account on a map using its billing address, with search and filters, and react when a marker is selected.

<!-- accountMap.html -->
<template>
    <avonni-dd-map
        header-caption="Query mode demo"
        header-title="Accounts"
        markers-title="Accounts"
        list-view="auto"
        show-footer
        zoom-level="4"
        query={accountQuery}
        mapping={accountMapping}
        filters={accountFilters}
        search-fields={accountSearchFields}
        onmarkerselect={handleMarkerSelect}
        onerror={handleError}
        onfilter={handleFilter}
    ></avonni-dd-map>
</template>

// accountMap.js
import { LightningElement } from 'lwc';

export default class AccountMap extends LightningElement {
    accountQuery = {
        objectApiName: 'Account',
        orderBy: 'Name ASC',
        limit: 200
    };

    accountMapping = {
        title: '{{Record.Name}}',
        value: '{{Record.Id}}',
        description: '{{Record.Industry}}',
        type: 'Pin',
        location: {
            Street: '{{Record.BillingStreet}}',
            City: '{{Record.BillingCity}}',
            State: '{{Record.BillingState}}',
            PostalCode: '{{Record.BillingPostalCode}}',
            Country: '{{Record.BillingCountry}}',
            Latitude: '{{Record.BillingLatitude}}',
            Longitude: '{{Record.BillingLongitude}}'
        }
    };

    accountSearchFields = ['Name'];
    accountFilters = ['Industry', 'BillingState'];

    handleMarkerSelect(event) {
        const { marker, selectedMarkerValue } = event.detail;
        // marker.title, selectedMarkerValue
    }

    handleError(event) {
        const message = event.detail.message;
    }

    handleFilter(event) {
        const value = event.detail.value;
    }
}

Result: A map with a Pin marker for each account, a searchable, filterable location list below it, and a footer. Selecting a marker fires markerselect with the marker and its source record.

Example 2: Static mode

Scenario: Display a fixed set of office locations with no query, mixing address-based and coordinate-based markers.

<!-- officeMap.html -->
<template>
    <avonni-dd-map
        header-caption="Static mode demo"
        header-title="Office locations"
        markers-title="Offices"
        list-view="auto"
        show-footer
        zoom-level="12"
        center={center}
        items={items}
        options={options}
        onmarkerselect={handleMarkerSelect}
    ></avonni-dd-map>
</template>

// officeMap.js
import { LightningElement } from 'lwc';

export default class OfficeMap extends LightningElement {
    items = [
        {
            title: 'Ferry Building',
            value: 'ferry-building',
            description: 'Historic marketplace on the Embarcadero.',
            type: 'Pin',
            location: { Latitude: 37.7955, Longitude: -122.3937 }
        },
        {
            title: 'Salesforce Tower',
            value: 'salesforce-tower',
            description: 'Tallest building in San Francisco.',
            type: 'Pin',
            location: {
                Street: '415 Mission Street',
                City: 'San Francisco',
                State: 'CA',
                PostalCode: '94105',
                Country: 'USA'
            }
        }
    ];

    center = { location: { Latitude: 37.7849, Longitude: -122.4094 } };
    options = { zoomControl: true, scrollwheel: true };

    handleMarkerSelect(event) {
        const { marker, markerSObject } = event.detail;
        // markerSObject is null in static mode
    }
}

Result: A map with two office markers placed from coordinates and from an address. There is no query—markers come straight from items, and markerselect fires with markerSObject set to null.

---

Specifications

Attributes

Name	Description	Type	Default	Required
center	Object defining the center of the map.	DdMapElementCenter	—
filters	Array of field API names that belong to the queried object. These fields will be displayed as user filters.	string[]	—
filters-attributes	Object defining the filters-specific attributes.	DdElementFiltersAttributes	—
header-actions	Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.	DdElementAction[]	—
header-avatar	Avatar displayed at the top left of the header.	DdElementAvatar	—
header-caption	Header caption, displayed above the title.	String	—
header-help-text	If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.	String	—
header-help-text-attributes	Object defining the help text-specific attributes.	DdElementHelpTextAttributes	—
header-title	Main title displayed in the header.	String	—
header-visible-actions-count	Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.	integer	—
items	Array of static markers displayed on the map. When this property is set, the map ignores the query and mapping properties and displays the markers directly.	DdMapItem[]	—
list-view	Specify how the list of locations is displayed. Valid values are visible, hidden and auto.	String	"auto"
mapping	Object defining the way the records returned by the query should be mapped to the map marker properties. To insert the value of a field, use the syntax {{Record.FieldApiName}}. For example, to use the value of the Name field, use {{Record.Name}}.	DdMapMapping	—
markers-title	Provides the heading title for the markers. The title is displayed below the map as a header for the list of clickable addresses. Required if specifying multiple markers.	String	—
options	Object defining a list of map settings/options.	DdMapElementOptions	—
query	Definition of the query to execute to get the records that will be mapped.	DdElementQuery	—
refresh-emp	Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.	DdElementRefreshEmp	—
search-attributes	Object defining the search-specific attributes.	DdElementSearchAttributes	—
search-fields	Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.	string[]	—
selected-marker-value	Value of the selected marker. Can be set to programmatically select a marker, and is updated automatically when the user selects one on the map.	String	—
show-footer	If true, the footer element is displayed below the map.	Boolean	false
side-panel-attributes	Object defining the side panel-specific attributes.	DdElementSidePanelAttributes	—
zoom-level	Zoom level of the map. Number between 0 and 23, 0 being the most zoomed out version of the map, and 23 the most zoomed in.	Number	10

Mapping

In query mode, mapping describes how each queried record becomes a marker. Insert a field value with the {{Record.FieldApiName}} syntax. Marker coordinates and addresses go under the location key.

const accountMapping = {
    title: '{{Record.Name}}',
    value: '{{Record.Id}}',
    description: '{{Record.Industry}}',
    type: 'Pin',
    location: {
        Street: '{{Record.BillingStreet}}',
        City: '{{Record.BillingCity}}',
        State: '{{Record.BillingState}}',
        PostalCode: '{{Record.BillingPostalCode}}',
        Country: '{{Record.BillingCountry}}',
        Latitude: '{{Record.BillingLatitude}}',
        Longitude: '{{Record.BillingLongitude}}'
    }
};

Mapping key	Description
title	Marker title shown in the location list.
value	Unique value identifying the marker (typically the record Id).
description	Secondary text for the marker.
type	Marker shape: default, Circle, Rectangle, Polygon, Pin, CustomIcon.
iconName	SLDS icon shown in the location list (e.g. standard:account).
location	Address (Street, City, State, PostalCode, Country) and/or Latitude / Longitude.

Methods

Name	Description	Argument Name	Argument Type	Argument Description
refresh	Refresh the query and the records displayed in the component.	stayOnCurrentPage	Boolean	If true, the component will refresh but stay on the current page.

Custom Events

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

markerselect

The event fired when a marker is selected.

The markerselect event returns the following parameters.

Parameter	Type	Description
marker	object	Selected marker, with its mapped display properties (title, description, value, location...).
markerSObject	object	Record corresponding to the selected marker. In static mode, no record is associated and this is null.
selectedMarkerValue	string	Value of the selected marker.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

error

The event fired when an error occurs in the component.

The error event returns the following parameters.

Parameter	Type	Description
message	string	Message of the error.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

filter

The event fired when the user filters the records.

The filter event returns the following parameters.

Parameter	Type	Description
value	object	Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

headeractionclick

The event fired when a header action is clicked.

The headeractionclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the action clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

markerselect

The event fired when a marker is selected.

The markerselect event returns the following parameters.

Parameter	Type	Description
marker	object	Selected marker, with its mapped display properties (title, description, value, location...).
markerSObject	object	Record corresponding to the selected marker. In static mode, no record is associated and this is null.
selectedMarkerValue	string	Value of the selected marker.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

nbitemschange

The event fired when the number of items displayed in the component changes.

The nbitemschange event returns the following parameters.

Parameter	Type	Description
value	integer	Number of items displayed in the component.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-dd-map-header-actions-color-background	color	—
--avonni-dd-map-header-actions-color-background-active	color	—
--avonni-dd-map-header-actions-color-background-hover	color	—
--avonni-dd-map-header-actions-color-border	color	—
--avonni-dd-map-header-actions-color-border-active	color	—
--avonni-dd-map-header-actions-color-border-hover	color	—
--avonni-dd-map-header-actions-text-color	color	—
--avonni-dd-map-header-actions-text-color-active	color	—
--avonni-dd-map-header-actions-text-color-hover	color	—
--avonni-dd-map-header-caption-font-family	string	—
--avonni-dd-map-header-caption-font-size	dimension	—
--avonni-dd-map-header-caption-font-style	string	normal
--avonni-dd-map-header-caption-font-weight	number	400
--avonni-dd-map-header-caption-letter-spacing	string	—
--avonni-dd-map-header-caption-line-height	string	—
--avonni-dd-map-header-caption-text-color	color	#000000
--avonni-dd-map-header-color-background	color	—
--avonni-dd-map-header-color-border	color	—
--avonni-dd-map-header-color-border-bottom	color	#c9c9c9
--avonni-dd-map-header-icon-color-background	color	—
--avonni-dd-map-header-icon-color-foreground	color	—
--avonni-dd-map-header-icon-color-foreground-default	color	—
--avonni-dd-map-header-icon-radius-border	string	—
--avonni-dd-map-header-margin-block-end	dimension	—
--avonni-dd-map-header-radius-border	string	—
--avonni-dd-map-header-sizing-border	string	—
--avonni-dd-map-header-sizing-border-bottom	dimension	1px
--avonni-dd-map-header-spacing-block-end	dimension	0.75rem
--avonni-dd-map-header-spacing-block-start	dimension	0.75rem
--avonni-dd-map-header-spacing-inline-end	dimension	1rem
--avonni-dd-map-header-spacing-inline-start	dimension	1rem
--avonni-dd-map-header-styling-border	string	—
--avonni-dd-map-header-styling-border-bottom	string	solid
--avonni-dd-map-header-title-font-family	string	—
--avonni-dd-map-header-title-font-size	dimension	1rem
--avonni-dd-map-header-title-font-style	string	normal
--avonni-dd-map-header-title-font-weight	number	400
--avonni-dd-map-header-title-letter-spacing	string	—
--avonni-dd-map-header-title-line-height	number	1.25
--avonni-dd-map-header-title-text-color	color	#080707
--avonni-dd-map-show-more-button-color-background	color	—
--avonni-dd-map-show-more-button-color-background-active	color	—
--avonni-dd-map-show-more-button-color-background-hover	color	—
--avonni-dd-map-show-more-button-color-border	color	—
--avonni-dd-map-show-more-button-color-border-active	color	—
--avonni-dd-map-show-more-button-color-border-hover	color	—
--avonni-dd-map-show-more-button-radius-border	string	—
--avonni-dd-map-show-more-button-sizing-border	string	—
--avonni-dd-map-show-more-button-spacing-block-end	dimension	—
--avonni-dd-map-show-more-button-spacing-block-start	dimension	—
--avonni-dd-map-show-more-button-spacing-inline-end	dimension	—
--avonni-dd-map-show-more-button-spacing-inline-start	dimension	—
--avonni-dd-map-show-more-button-text-color	color	—
--avonni-dd-map-show-more-button-text-color-active	color	—
--avonni-dd-map-show-more-button-text-color-hover	color	—

Key Considerations

• Mode selection: Setting items switches the component to static mode and ignores query and mapping. Leave items unset for query mode.
• Locations: Markers can be placed by coordinates (Latitude/Longitude) or by a full address; coordinates are the most reliable.
• Markers title: markers-title is required when displaying multiple markers, and labels the location list below the map.
• Static records: In static mode there is no underlying record, so markerselect returns markerSObject as null.
• Zoom range: zoom-level must be between 0 and 23; out-of-range values fall back to the default of 10.
• Best Practice: In query mode, always provide both Latitude and Longitude in the mapping when records store coordinates—this places markers precisely and avoids relying on address geocoding. Set markers-title whenever more than one marker is displayed.

---

Troubleshooting Common Issues

• Markers not appearing: Confirm each marker has a valid location—either coordinates or a complete, geocodable address.
• Map shows no records (query mode): Verify query.objectApiName is correct and the mapping location keys point to populated address/coordinate fields; listen to the error event for query failures.
• Wrong marker selected programmatically: Ensure selected-marker-value matches a marker's value exactly (typically the record Id in query mode).
• If issues persist: Contact our support team at [email protected] for assistance.