> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/data-driven-components/leaflet-map.md).

# Leaflet Map

`avonni-dd-leaflet-map`

The Avonni Data Driven Leaflet displays records as markers on a Leaflet map.

## Overview

**Leaflet Map** is a data-driven Lightning Web Component for Leaflet maps, with marker clustering, drawing tools, multi-stop route planning, and drawings saved as files.

**Query mode** runs `query` and maps each record with `mapping` and the optional `fields`. **Static mode** renders a fixed `items` array and ignores those three. The examples shipped with the component use query mode on Accounts.

### Use Cases

* **Dashboards and asset geolocation:** many records, equipment or vehicles by coordinates, clustered.
* **Field mapping and coverage areas:** circles, polygons or polylines drawn by users, captured as GeoJSON or saved as a file.
* **Static location boards:** fixed points of interest.
* **Route planning:** leg distances and times, each stop opened in Google Maps or Waze.

***

## Use Case Examples

### Example 1: Query mode

**Scenario:** accounts at their billing coordinates, clustered, with a marker selection handler.

```html
<!-- accountLeafletMap.html -->
<template>
    <avonni-dd-leaflet-map
        header-caption="Query mode demo"
        header-title="Accounts"
        zoom-level="4"
        center={center}
        cluster
        query={accountQuery}
        mapping={accountMapping}
        fields={accountFields}
        search-fields={accountSearchFields}
        filters={accountFilters}
        onmarkerselect={handleMarkerSelect}
        onerror={handleError}
    ></avonni-dd-leaflet-map>
</template>
```

```js
// accountLeafletMap.js
import { LightningElement } from 'lwc';

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

    accountMapping = {
        title: '{{Record.Name}}',
        value: '{{Record.Id}}',
        description: '{{Record.Industry}}',
        type: 'Pin',
        location: {
            Latitude: '{{Record.BillingLatitude}}',
            Longitude: '{{Record.BillingLongitude}}'
        }
    };

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

    center = { location: { Latitude: 39.5, Longitude: -98.35 } };

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

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

**Result:** clustered pins, a header search box and Industry filter. A pin's popup shows the name, industry and fields; `markerselect` returns the marker and its record (`markerSObject`).

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2F94ciJ5IGuG8sq9CAP0y5%2Fleaflet-map-example-accounts.png?alt=media" alt="A Leaflet map of the United States titled Accounts, with a search box and filter in the header, red account pins and numbered cluster bubbles"><figcaption><p>Example 1 on sample accounts: the map opens on the center of the United States, and nearby pins merge into cluster bubbles.</p></figcaption></figure>

### Example 2: Static mode

**Scenario:** fixed offices by coordinates, a pin and a coverage circle, no query.

```html
<!-- officeLeafletMap.html -->
<template>
    <avonni-dd-leaflet-map
        header-caption="Static mode demo"
        header-title="Office locations"
        zoom-level="12"
        center={center}
        items={items}
        onmarkerselect={handleMarkerSelect}
    ></avonni-dd-leaflet-map>
</template>
```

```js
// officeLeafletMap.js
import { LightningElement } from 'lwc';

export default class OfficeLeafletMap 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: 'Golden Gate Park',
            value: 'golden-gate-park',
            description: 'Large urban park stretching to the Pacific.',
            type: 'Circle',
            radius: 800,
            fillColor: '#04844b',
            fillOpacity: 0.3,
            strokeColor: '#04844b',
            location: { Latitude: 37.7694, Longitude: -122.4862 }
        }
    ];

    center = { location: { Latitude: 37.7849, Longitude: -122.4094 } };

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

**Result:** a pin and a green circle. Static mode has no record: `markerselect` returns `markerSObject` as `null`.

***

## Popup

A marker's popup shows its `title`, `description`, `imageSrc` image, `infos` links and `fields` values. Width: `popup-width`. Image layout: `image-attributes`.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2F4oYCVUCn60N0jLNqZoyT%2Fmap-popup.png?alt=media" alt="A Leaflet map titled Customer visits with the popup of Juniper Health open above its marker. The popup shows an illustration across its top, the title Juniper Health, the description Hyde Park clinic, a Visit website link, the fields Industry, Healthcare and Employees, 240, and an Add Stop button. A route button sits at the top right of the map."><figcaption><p>A marker popup. The image, the link and the fields come from the mapping and the fields list, and the Add Stop button appears when routing is on.</p></figcaption></figure>

***

## Search and Filters

`search-fields` adds a search box, `filters` a filter per field: in the header, or in a side panel when `filters-attributes` `type` and `search-attributes` `position` are `panel`.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FXB6bNEn6sdLct5CNdTnZ%2Fmap-side-panel.png?alt=media" alt="A Leaflet map titled Customer sites with a side panel on its left. The panel holds a Search sites box, an Industry filter listing Healthcare, Manufacturing, Retail, Technology and Transportation, an Account Type filter with Customer - Direct checked and Prospect unchecked, and a Clear all selections button. Both filters show an Equals filter mode button. The header reads 3 items found, Filtered by Account Type, and carries two actions, Log Visit and Share, and the button that shows or hides the panel. Three markers remain on the map."><figcaption><p>Filters and search in the side panel beside the map. Checking Customer - Direct leaves three sites on the map, and Clear all selections resets every filter.</p></figcaption></figure>

***

## Drawing

`drawable` adds the drawing tools, set with `draw-attributes`.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FFxHhEY24p9ATDxKkCONH%2Fmap-draw.png?alt=media" alt="A Leaflet map titled Sales territories with five red markers in Chicago. A polygon outlined and filled in blue covers the north side and two of the markers. At the bottom right, the drawing toolbar shows Line, Polygon, Circle and Marker buttons, then Edit and Delete, above the zoom buttons, and a Save button sits in the bottom right corner of the map."><figcaption><p>Drawing on a Leaflet map: a territory loaded as the starting drawing, the drawing toolbar at the bottom right, and the Save button.</p></figcaption></figure>

* **Value:** GeoJSON in `draw-geo-json-value` and the `drawvaluechange` event.
* **File:** `save-as-content-document` saves a `ContentDocument` (`content-document-attributes`); `contentdocumentidchange` returns its Id.

***

## Route Planning

`routing` turns markers into a driving route of up to 25 stops.

{% hint style="info" %}
An administrator enables routing once in the LWC Components package, with an OpenRouteService or Mapbox key: see [Enable Map Routing](/lwc-components/data-driven-components/leaflet-map/enable-map-routing.md).
{% endhint %}

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FGb04QQ00fgCD0zGQlpdY%2Frouting-route-panel.png?alt=media" alt="A Leaflet map of Chicago titled Customer visits with five numbered stops joined by a driving route. The Route panel floats over the right of the map: 10:05 AM to 2:06 PM and 4 hr 1 min, the Starting point search, the five stops with an arrival time for each stop after the first, Settings folded, then the Calculate route and download buttons. Add Multiple Stops sits at the top of the map."><figcaption><p>A calculated route with the panel overlaid on the map. With Mapbox, the panel shows when the route starts and ends and when each stop is reached.</p></figcaption></figure>

| Control               | What it does                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Route** button      | Opens and closes the panel. In the header, or on the map when the panel is overlaid.                                      |
| **Starting point**    | **My position**, or one of the map's markers.                                                                             |
| Drag handle           | Reorders the stops.                                                                                                       |
| Stop menu             | **Remove**, **Google Maps**, **Waze**.                                                                                    |
| **Optimize**          | Reorders the stops to shorten the drive.                                                                                  |
| **Clear**, undo, redo | Empties the route, or steps through your changes.                                                                         |
| **Settings**          | Lunch, end of day, visit duration, roads to avoid. With Mapbox, **Timing**: **Leave now**, **Leave at** or **Arrive by**. |
| **Calculate route**   | Gets the driving route from the provider.                                                                                 |
| Download              | Exports the calculated route as a CSV file.                                                                               |

### Adding Stops

With the panel open, click a marker or its popup's **Add Stop** (**Remove Stop**). **Add Multiple Stops** adds every marker in a drawn rectangle or lasso; `disable-multi-stop-selection` removes it.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2Fvaq9Gdm67nlum6g10qnm%2Fmap-route-multi-stop.png?alt=media" alt="Part of a Leaflet map with the Route panel open. At the top of the map, Add Multiple Stops has opened into two buttons, a rectangle tool, selected, and a lasso tool. Two stops, Atlas Logistics and Blue Finch Retail, are numbered 1 and 2 on the map and listed in the panel above Settings and Calculate route. Three markers not yet in the route are still red pins."><figcaption><p>Add Multiple Stops opens a rectangle tool and a lasso tool. Drawing a shape on the map adds every marker inside it to the route.</p></figcaption></figure>

### Settings and Arrival Times

With Mapbox, the panel shows arrival times and flags stops reached after **End of day**.

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FeMOsVXbAwNiBH48rbr51%2Fmap-route-settings.png?alt=media" alt="The Route panel with its Settings section open. Lunch start 12:00 p.m., Lunch end 1:00 p.m., End of day 6:00 p.m., Visit duration (minutes) 30, Timing set to Leave at, Date Nov 14, 2026, Time 8:00 a.m., then three switches, Avoid ferries, Avoid highways and Avoid tolls, all off. The Calculate route button sits at the bottom of the panel." width="320"><figcaption><p>The Settings section of the Route panel. Timing is set to Leave at, which shows the Date and Time fields; apart from the date, every value is the default.</p></figcaption></figure>

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FuHjffwilMix0C6UGSWvu%2Fmap-route-end-of-day.png?alt=media" alt="A Leaflet map titled Customer visits with five numbered stops in Chicago and the calculated driving route. The Route panel on the right reads 11:00 AM to 3:08 PM, 4 hr 8 min, followed by a red note: This route finishes after the end of day. Remove a stop, or start earlier. Stops 1 to 4 are blue and show their arrival times. Stop 5, Juniper Health, is orange, arrives at 3:08 PM and is flagged Past end of day, and the last leg of the route, from stop 4 to stop 5, is drawn in orange."><figcaption><p>A route that runs past the end of day: the late stop and the drive to it turn orange, its row is flagged Past end of day, and a note at the top of the panel says the route finishes too late.</p></figcaption></figure>

### Route Panel Attributes

`route-panel-attributes` places the panel. On a narrow map, the panel overlays the map whatever `overlay` says.

| Key               | Type    | Description                                                                                                                                                 |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `position`        | String  | Side of the map the panel is placed on: `left` or `right`. Defaults to `right`.                                                                             |
| `openedByDefault` | Boolean | If true, the panel is open when the map first loads, so marker clicks add stops right away. Defaults to `false`.                                            |
| `overlay`         | Boolean | If true, the **Route** button sits on the map and the panel floats over it as a full-height card instead of taking a column beside it. Defaults to `false`. |

<figure><img src="https://2403786217-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPjQbBtFNxVSSOtnsjuwx%2Fuploads%2FfTmDHgCQNXeSJLdXFYII%2Fmap-route-beside.png?alt=media" alt="A Leaflet map titled Customer visits with the Route panel as a column on its right, outside the map. In the header, the Route button is selected. Five numbered stops in Chicago are joined by straight lines in the order of the list, and the panel lists them under Starting point, with Settings and the Calculate route button below."><figcaption><p>When the Route panel is not overlaid on the map, it opens as a column beside it, and the Route button in the header shows or hides it. The route is not calculated yet, so the stops are joined by straight lines.</p></figcaption></figure>

<details>

<summary>Route troubleshooting</summary>

* **No Route button:** `routing` is off, or routing is not enabled in the LWC Components package.
* **Straight line instead of roads:** provider unreachable or out of quota (the panel says which); the line keeps the stop order. If every route falls back, check that the Remote Site Setting for the provider's host is active ([Enable Map Routing](/lwc-components/data-driven-components/leaflet-map/enable-map-routing.md)).
* **No timing or arrival times:** OpenRouteService has no traffic model. Departure and arrival times, and the CSV **Arrival Time** column, are Mapbox only.
* **No Add Multiple Stops button:** clear `disable-multi-stop-selection`.

</details>

***

## Specifications

### Attributes

| Name                           | Description                                                                                                                                                                                                                                              | Type                                  | Default         | Required |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------- | -------- |
| `center`                       | Object defining the center of the map.                                                                                                                                                                                                                   | DdLeafletMapCenter                    | —               |          |
| `cluster`                      | If true, nearby markers are automatically grouped into clusters to improve map performance and readability.                                                                                                                                              | Boolean                               | `false`         |          |
| `cluster-attributes`           | Object defining the attributes of the cluster.                                                                                                                                                                                                           | DdLeafletMapClusterAttributes         | —               |          |
| `content-document-attributes`  | Object defining the attributes of the content document to display on the map when the `saveAsContentDocument` property is true.                                                                                                                          | DdLeafletMapContentDocumentAttributes | —               |          |
| `disable-multi-stop-selection` | If true, disables the area-select tool that lets users add many stops to a route at once by drawing a rectangle or lasso. Only relevant in route mode.                                                                                                   | Boolean                               | `false`         |          |
| `draw-attributes`              | Object defining the attributes of the drawing tools to display on the map.                                                                                                                                                                               | DdLeafletMapDrawAttributes            | —               |          |
| `draw-geo-json-value`          | The GeoJSON value of the drawing on the map.                                                                                                                                                                                                             | String                                | —               |          |
| `drawable`                     | If true, users can select drawing tools to draw shapes directly on the map. The property `drawGeoJsonValue` gets updated.                                                                                                                                | Boolean                               | `false`         |          |
| `enable-multi-select-markers`  | If true, users can select multiple markers at once by holding the Ctrl (or Cmd) key while clicking. Clicking the map background or pressing Escape clears the selection.                                                                                 | Boolean                               | `false`         |          |
| `fields`                       | Array of field API names that belong to the queried object. The fields will be displayed in the list view items, with their corresponding values.                                                                                                        | string\[]                             | —               |          |
| `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            | —               |          |
| `geo-json-value`               | The GeoJSON value of the map.                                                                                                                                                                                                                            | String                                | —               |          |
| `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                               | —               |          |
| `image-attributes`             | Object defining the attributes of the image to display on the map.                                                                                                                                                                                       | DdLeafletMapImageAttributes           | —               |          |
| `items`                        | Array of static markers displayed on the map. When this property is set, the map ignores the `query`, `mapping` and `fields` properties and displays the markers directly.                                                                               | DdLeafletMapItem\[]                   | —               |          |
| `mapping`                      | Object defining the way the records returned by the query should be mapped to the map item 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}}`. | DdLeafletMapMapping                   | —               |          |
| `options`                      | Object defining a list of map settings/options.                                                                                                                                                                                                          | DdMapElementOptions                   | —               |          |
| `popup-width`                  | Width of the popup displayed when a marker is selected.                                                                                                                                                                                                  | Number                                | —               |          |
| `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                   | —               |          |
| `route-panel-attributes`       | Object defining the placement and default state of the route panel. Only relevant when `routing` is true.                                                                                                                                                | DdLeafletMapRoutePanelAttributes      | —               |          |
| `routing`                      | If true, a route panel lets the user order the visible markers into a route and displays the driving directions between them. Requires an administrator to have enabled routing in the Avonni Settings tab.                                              | Boolean                               | `false`         |          |
| `save-as-content-document`     | If true, the drawing on the map is saved as a `ContentDocument` object (file).                                                                                                                                                                           | Boolean                               | `false`         |          |
| `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 currently selected marker. Updated automatically when a marker is selected via the map.                                                                                                                                                     | String                                | —               |          |
| `side-panel-attributes`        | Object defining the side panel-specific attributes.                                                                                                                                                                                                      | DdElementSidePanelAttributes          | —               |          |
| `zoom-controls-position`       | Position of the zoom controls on the map. Valid values are `topleft`, `topright`, `bottomleft` and `bottomright`.                                                                                                                                        | String                                | `"bottomright"` |          |
| `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

`mapping` turns each queried record into a marker; `{{Record.FieldApiName}}` inserts a field value. Leaflet places markers by coordinates only: every `location`, mapped or static, must resolve to `Latitude` and `Longitude`.

```js
const accountMapping = {
    title: '{{Record.Name}}',
    value: '{{Record.Id}}',
    description: '{{Record.Description}}',
    type: 'Pin',
    location: {
        Latitude: '{{Record.BillingLatitude}}',
        Longitude: '{{Record.BillingLongitude}}'
    }
};
```

| Mapping key            | Description                                                                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                | Marker title, shown in bold at the top of the marker popup.                                                                                                                 |
| `value`                | Unique value identifying the marker (typically the record Id).                                                                                                              |
| `description`          | Secondary text shown under the title in the popup.                                                                                                                          |
| `type`                 | Marker shape: `default`, `Circle`, `Rectangle`, `Polygon`, `Pin`, `CustomIcon`.                                                                                             |
| `iconName`             | Accepted for parity with the Google Maps component; not displayed by the Leaflet map.                                                                                       |
| `imageSrc`             | Image shown in the marker popup.                                                                                                                                            |
| `infos`                | Links shown in the marker popup.                                                                                                                                            |
| `markerTypeAttributes` | Shape styling: `radius`, fill and stroke for `Circle`, `Rectangle` and `Polygon`, `mapIcon` for `Pin`. In static mode, put these keys at the top level of the item instead. |
| `location`             | `Latitude` / `Longitude` coordinates used to place the marker.                                                                                                              |

The `Street`, `City`, `State`, `PostalCode` and `Country` keys of `location` only feed the search; they never place a marker.

### Object Attributes

Keys of each object attribute. `route-panel-attributes`: see [Route Panel Attributes](#route-panel-attributes).

{% tabs %}
{% tab title="Query and refresh" %}
`query`

| Key             | Type      | Description                                                                                 |
| --------------- | --------- | ------------------------------------------------------------------------------------------- |
| `objectApiName` | String    | Required. Object to query.                                                                  |
| `filter`        | String    | SOQL WHERE expression, e.g. `AccountId IN (SELECT Id FROM Account WHERE Name LIKE '%Doe')`. |
| `orderBy`       | String    | SOQL ORDER BY expression, e.g. `Name ASC, AnnualRevenue DESC`.                              |
| `limit`         | Integer   | Maximum number of records.                                                                  |
| `addedFields`   | String\[] | Extra fields to query outside the mapping, e.g. for a record returned by an event.          |

`refresh-emp`

| Key             | Type   | Description                                                                                |
| --------------- | ------ | ------------------------------------------------------------------------------------------ |
| `channelName`   | String | Required. Platform event, e.g. `yournamespace__New_Contact__e`.                            |
| `keyFieldName`  | String | Event field to match. Empty: every event refreshes.                                        |
| `keyFieldValue` | String | Value the key field must match. Empty: refresh when the key field value is in the records. |
| {% endtab %}    |        |                                                                                            |

{% tab title="Center and options" %}
`center`

| Key                    | Type    | Description                                                                                |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `location`             | Object  | `Latitude` and `Longitude`.                                                                |
| `displayAsMarker`      | Boolean | Show the center as a marker. Defaults to `false`.                                          |
| `markerType`           | String  | `default`, `Circle`, `Rectangle`, `Polygon`, `Pin` or `CustomIcon`. Defaults to `default`. |
| `markerTypeAttributes` | Object  | Same keys as in [Mapping](#mapping).                                                       |

`options`

| Key                      | Type    | Description                 |
| ------------------------ | ------- | --------------------------- |
| `draggable`              | Boolean | Users can drag the map.     |
| `disableDoubleClickZoom` | Boolean | Double-click does not zoom. |
| `scrollwheel`            | Boolean | Mouse wheel zooms.          |
| `zoomControl`            | Boolean | Show the zoom controls.     |
| {% endtab %}             |         |                             |

{% tab title="Clustering" %}
`cluster-attributes`

| Key                       | Type    | Description                                                              |
| ------------------------- | ------- | ------------------------------------------------------------------------ |
| `maxClusterRadius`        | Integer | Pixels a cluster covers from its central marker. Defaults to `80`.       |
| `disableClusteringAtZoom` | Integer | Zoom level at which clustering stops.                                    |
| `showCoverageOnHover`     | Boolean | Hovering a cluster shows the bounds of its markers. Defaults to `false`. |
| {% endtab %}              |         |                                                                          |

{% tab title="Drawing and file" %}
`draw-attributes`

| Key                 | Type      | Description                                                                      |
| ------------------- | --------- | -------------------------------------------------------------------------------- |
| `drawTools`         | String\[] | `circle`, `marker`, `polygon`, `polyline`, `edit`, `delete`.                     |
| `drawToolsPosition` | String    | `topleft`, `topright`, `bottomleft` or `bottomright`. Defaults to `bottomright`. |

`content-document-attributes`

| Key                             | Type    | Description                                       |
| ------------------------------- | ------- | ------------------------------------------------- |
| `contentDocumentId`             | String  | File to display on the map.                       |
| `contentDocumentLinkedEntityId` | String  | Record the file is linked to.                     |
| `contentDocumentTitle`          | String  | File title.                                       |
| `saveAsButtonLabel`             | String  | Label of the save button.                         |
| `autoSaveContentDocument`       | Boolean | Save automatically when the user changes the map. |
| {% endtab %}                    |         |                                                   |

{% tab title="Image" %}
`image-attributes`

| Key             | Type   | Description                                                                                           |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `position`      | String | `left`, `right`, `top` or `bottom`. Defaults to `left`.                                               |
| `size`          | String | `small`, `medium` or `large`: the width for `left` and `right`, else the height. Defaults to `large`. |
| `width`         | Number | Pixels, for `left` and `right`. Overrides `size`.                                                     |
| `height`        | Number | Pixels, for `top` and `bottom`. Overrides `size`.                                                     |
| `cropFit`       | String | `cover`, `contain`, `fill` or `none`. Defaults to `cover`.                                            |
| `cropPositionX` | Number | Crop position, horizontal, in percent.                                                                |
| `cropPositionY` | Number | Crop position, vertical, in percent.                                                                  |
| `fallbackSrc`   | String | Image used when a marker's image is missing or invalid.                                               |
| {% endtab %}    |        |                                                                                                       |

{% tab title="Header" %}
`header-actions` (each action)

| Key               | Type    | Description                                |
| ----------------- | ------- | ------------------------------------------ |
| `name`            | String  | Required. Returned by `headeractionclick`. |
| `label`           | String  | Required. Button label.                    |
| `iconName`        | String  | Icon, e.g. `standard:account`.             |
| `alternativeText` | String  | Icon alternative text.                     |
| `title`           | String  | Hover title.                               |
| `disabled`        | Boolean | Shown disabled. Defaults to `false`.       |

`header-avatar`

| Key                | Type   | Description                                                             |
| ------------------ | ------ | ----------------------------------------------------------------------- |
| `src`              | String | Image URL.                                                              |
| `fallbackIconName` | String | Required. Icon if the image fails, also the initials' background color. |
| `initials`         | String | Shown if the image fails.                                               |
| `alternativeText`  | String | Alternative text.                                                       |
| `size`             | String | `xx-small` to `xxx-large`. Defaults to `medium`.                        |
| `variant`          | String | `circle` or `square`. Defaults to `square`.                             |

`header-help-text-attributes`

| Key               | Type   | Description                                                  |
| ----------------- | ------ | ------------------------------------------------------------ |
| `iconName`        | String | Defaults to `utility:info`.                                  |
| `iconVariant`     | String | `bare`, `inverse`, `warning` or `error`. Defaults to `bare`. |
| `alternativeText` | String | Icon alternative text.                                       |
| {% endtab %}      |        |                                                              |

{% tab title="Search and filters" %}
`filters-attributes`

| Key                       | Type    | Description                                                   |
| ------------------------- | ------- | ------------------------------------------------------------- |
| `type`                    | String  | `horizontal`, `popover` or `panel`. Defaults to `horizontal`. |
| `hidePicklistEmptyValues` | Boolean | Hide unused picklist values. Defaults to `false`.             |
| `picklistFilterSortOrder` | String  | `asc` or `desc`. Defaults to `asc`.                           |

`search-attributes`

| Key           | Type   | Description                                                                |
| ------------- | ------ | -------------------------------------------------------------------------- |
| `placeholder` | String | Defaults to `Search`.                                                      |
| `position`    | String | `left`, `center`, `fill`, `right` (header) or `panel`. Defaults to `left`. |

`side-panel-attributes`

| Key                | Type    | Description                                        |
| ------------------ | ------- | -------------------------------------------------- |
| `position`         | String  | `left` or `right`. Defaults to `left`.             |
| `isClosed`         | Boolean | Closed on load. Defaults to `false`.               |
| `hideToggleButton` | Boolean | Hide the show or hide button. Defaults to `false`. |
| {% endtab %}       |         |                                                    |
| {% endtabs %}      |         |                                                    |

### 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

#### `centerchange`

The event fired when the center location of the map is updated.

The `centerchange` event returns the following parameters.

| Parameter  | Type                       | Description                     |
| ---------- | -------------------------- | ------------------------------- |
| `location` | DdLeafletMapMarkerLocation | New center location of the map. |

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.                        |

#### `contentdocumentidchange`

The event fired when the content document ID changes.

The `contentdocumentidchange` event returns the following parameters.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| `value`   | string | New content document ID. |

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.                        |

#### `drawvaluechange`

The event fired when the draw value is updated.

The `drawvaluechange` event returns the following parameters.

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| `value`   | string | New draw geo JSON value. |

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.                        |

#### `markercreated`

The event fired when a marker is created.

The `markercreated` event returns the following parameters.

| Parameter  | Type                       | Description                                 |
| ---------- | -------------------------- | ------------------------------------------- |
| `location` | DdLeafletMapMarkerLocation | Object defining the location of the 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.                        |

#### `markerdrag`

The event fired when a marker is dragged.

The `markerdrag` event returns the following parameters.

| Parameter  | Type                       | Description             |
| ---------- | -------------------------- | ----------------------- |
| `record`   | object                     | Record of the marker.   |
| `location` | DdLeafletMapMarkerLocation | Location of the 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.                        |

#### `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.                        |

#### `markerunselect`

The event fired when a marker is unselected. Only fired when `enableMultiSelectMarkers` is true, either by Ctrl/Cmd clicking a selected marker again or by clearing the selection.

The `markerunselect` event returns the following parameters.

| Parameter       | Type   | Description                                                                                                |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `marker`        | object | Unselected marker, with its mapped display properties (`title`, `description`, `value`, `location`...).    |
| `markerSObject` | object | Record corresponding to the unselected marker. In static mode, no record is associated and this is `null`. |

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.                        |

#### `zoomlevelchange`

The event fired when the zoom level is updated.

The `zoomlevelchange` event returns the following parameters.

| Parameter | Type   | Description     |
| --------- | ------ | --------------- |
| `value`   | number | New zoom level. |

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-leaflet-map-header-actions-color-background`        | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-color-background-active` | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-color-background-hover`  | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-color-border`            | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-color-border-active`     | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-color-border-hover`      | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-text-color`              | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-text-color-active`       | color     | —         |
| `--avonni-dd-leaflet-map-header-actions-text-color-hover`        | color     | —         |
| `--avonni-dd-leaflet-map-header-caption-font-family`             | string    | —         |
| `--avonni-dd-leaflet-map-header-caption-font-size`               | dimension | —         |
| `--avonni-dd-leaflet-map-header-caption-font-style`              | string    | `normal`  |
| `--avonni-dd-leaflet-map-header-caption-font-weight`             | number    | `400`     |
| `--avonni-dd-leaflet-map-header-caption-letter-spacing`          | string    | —         |
| `--avonni-dd-leaflet-map-header-caption-line-height`             | string    | —         |
| `--avonni-dd-leaflet-map-header-caption-text-color`              | color     | `#000000` |
| `--avonni-dd-leaflet-map-header-color-background`                | color     | —         |
| `--avonni-dd-leaflet-map-header-color-border`                    | color     | —         |
| `--avonni-dd-leaflet-map-header-color-border-bottom`             | color     | `#c9c9c9` |
| `--avonni-dd-leaflet-map-header-icon-color-background`           | color     | —         |
| `--avonni-dd-leaflet-map-header-icon-color-foreground`           | color     | —         |
| `--avonni-dd-leaflet-map-header-icon-color-foreground-default`   | color     | —         |
| `--avonni-dd-leaflet-map-header-icon-radius-border`              | string    | —         |
| `--avonni-dd-leaflet-map-header-margin-block-end`                | dimension | —         |
| `--avonni-dd-leaflet-map-header-radius-border`                   | string    | —         |
| `--avonni-dd-leaflet-map-header-sizing-border`                   | string    | —         |
| `--avonni-dd-leaflet-map-header-sizing-border-bottom`            | dimension | `1px`     |
| `--avonni-dd-leaflet-map-header-spacing-block-end`               | dimension | `0.75rem` |
| `--avonni-dd-leaflet-map-header-spacing-block-start`             | dimension | `0.75rem` |
| `--avonni-dd-leaflet-map-header-spacing-inline-end`              | dimension | `1rem`    |
| `--avonni-dd-leaflet-map-header-spacing-inline-start`            | dimension | `1rem`    |
| `--avonni-dd-leaflet-map-header-styling-border`                  | string    | —         |
| `--avonni-dd-leaflet-map-header-styling-border-bottom`           | string    | `solid`   |
| `--avonni-dd-leaflet-map-header-title-font-family`               | string    | —         |
| `--avonni-dd-leaflet-map-header-title-font-size`                 | dimension | `1rem`    |
| `--avonni-dd-leaflet-map-header-title-font-style`                | string    | `normal`  |
| `--avonni-dd-leaflet-map-header-title-font-weight`               | number    | `400`     |
| `--avonni-dd-leaflet-map-header-title-letter-spacing`            | string    | —         |
| `--avonni-dd-leaflet-map-header-title-line-height`               | number    | `1.25`    |
| `--avonni-dd-leaflet-map-header-title-text-color`                | color     | `#080707` |

## Key Considerations

* **Initial view:** without `center`, the map opens on the first marker with coordinates, at `zoom-level`, without fitting all markers.
* **Map height:** 16:9 of its width.
* **Clustering:** use `cluster` when a query can return many markers; it keeps the map responsive and readable.

***

## Troubleshooting Common Issues

* **Markers not appearing:** no valid coordinates in `location` (see [Mapping](#mapping)).
* **No records (query mode):** check `query.objectApiName` and the mapped coordinate fields; the `error` event reports query failures.
* **Drawing not saved:** `save-as-content-document` must be `true`, with `content-document-attributes`; `contentdocumentidchange` returns the file Id.
* **Route issues:** see **Route troubleshooting** in [Route Planning](#route-planning).
* **If issues persist:** contact <support@avonni.app>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/lwc-components/data-driven-components/leaflet-map.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.