> 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/map.md).

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

```html
<!-- 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>
```

```js
// 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.

```html
<!-- 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>
```

```js
// 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.

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

### 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 <support@avonni.app> for assistance.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.