> 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/dynamic-components/components/map.md).
# Map
The Avonni Map component displays interactive geographic data using Google Maps or Leaflet. Use it to visualize Salesforce records as markers, shapes, or custom icons on a fully configurable map — with support for searching, filtering, clustering, drawing, and header actions.
## Overview
{% hint style="warning" %}
**Note on Advanced Map Features**
For advanced functionality such as **map clustering**, interactive **drawing**, and working with **GeoJSON** data, we recommend using the [**Avonni Map component for Screen Flows**](/flow/flow-components/map.md)
{% endhint %}
## Configuration
To configure the Map, select it on the canvas. The **Edit Map** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.
### Data Source
Before you build your map, you must tell the component where to get the location data it should display.
Manual
Enter data directly into the component configuration.
Variable
This is useful for data that changes based on user interactions or other component logic.
Query
This is the most common option for displaying Salesforce records.
### Data Mapping
When using a dynamic data source, configure the **Data Mappings** section to connect fields from your Salesforce data to the map's marker attributes — for example, link your address field to the **Location** attribute so each record is plotted at the correct place.
Beyond location, Data Mappings also control how each marker looks. Locate the **Type** attribute to choose a marker shape, and use the related styling fields to apply fill color, stroke, and scale. Because these are data-driven mappings, you can point them at formula fields to color-code markers automatically — for example, coloring Account markers by industry.
**Marker type options**
* **Default** — standard map pin.
* **Circle** — circular area; requires a **Radius** (in meters).
* **Rectangle** — rectangular area; requires **Bounds** (north/south/east/west coordinates).
* **Polygon** — custom multi-sided shape; requires **Paths** (list of lat/lng coordinates).
* **Pin** — classic pin shape with icon styling.
* **Custom Icon** — fully custom SVG icon via an SVG path definition.
### Content
To configure the Map, select it on the canvas and open the **Content** section of the Properties panel.
#### Type
Choose the map provider. **Google Maps** is the default and supports address-based geocoding — ideal when your records contain street addresses and you have fewer than 100 markers. **Leaflet** is an open-source alternative that handles large datasets with hundreds or thousands of markers, and unlocks advanced features like marker clustering, drawing tools, and GeoJSON support.
{% hint style="info" %}
If Leaflet is selected, you must add `https://tile.openstreetmap.org` to **Trusted Sites** in your Salesforce org for the map tiles to load.
{% endhint %}
#### List View
Controls whether the sidebar list of locations is shown alongside the map. Options: **Visible**, **Hidden**, or **Auto** (default — shown when multiple markers are present). When visible, set the **List Title** to display a heading above the marker list.
#### Zoom Level
Sets the initial zoom level when the map loads, from 0 (world view) to 23 (building level).
#### Interaction Controls
* **Disable Dragging** — prevents users from panning the map.
* **Disable Scroll Wheel Zooming** — disables zoom via scroll wheel (available when dragging is not disabled).
* **Disable Double Click Zoom** — disables zoom on double-click (available when dragging is not disabled).
* **Hide Zoom Controls** — hides the zoom in/out buttons.
#### Additional Controls (Google Maps only)
* **Disable Default UI** — removes the built-in Map/Satellite toggle buttons.
* **Show Footer** — displays a footer bar below the map.
#### Additional Controls (Leaflet only)
* **Zoom Controls Position** — positions the zoom buttons at one of the map corners: Bottom Right (default), Bottom Left, Top Right, or Top Left.
* **Tile Layer** — override the default OpenStreetMap tiles with a custom tile URL template.
#### Selected Marker Value
Pre-selects a marker on load by providing its unique value. This is useful for linking the map to another component — for example, highlighting the marker that corresponds to a selected record in a list.
### Map Center Location
Defines where the map is centered when it first loads.
* **Latitude / Longitude** — enter decimal coordinates to pin an exact center point.
* **Address fields (Google Maps only)** — provide a **Street**, **City**, **State**, **Postal Code**, and **Country** to geocode the center point from an address.
* **Display As Marker** — when enabled, places a visible marker at the center point. Use the **Type** dropdown to choose the marker shape (Default, Circle, Rectangle, Polygon, Pin, or Custom Icon), then configure the shape-specific attributes (radius, bounds, paths, icon styling) that appear based on your selection.
Any of these fields can be bound to a Variable resource so the center updates dynamically as users interact with the page.
### Marker Clustering *(Leaflet only)*
Groups nearby markers into clusters to improve performance and readability when displaying large datasets.
* **Enable Marker Clustering** — turns clustering on.
* **Coverage On Hover** — when enabled, hovering over a cluster shows the boundary that encompasses all its markers.
* **Max Cluster Radius** — the maximum distance in pixels from the central marker that a cluster will cover (default: 80).
* **Disable Clustering Zoom Level** — at this zoom level and below, markers are no longer grouped into clusters.
### Draw *(Leaflet only)*
Enables users to draw shapes directly on the map and optionally save them as Salesforce files.
* **Enable Draw** — activates the drawing toolbar. The output attribute **Draw GeoJSON Value** is updated as shapes are drawn.
* **Draw GeoJSON Value** — supply an initial GeoJSON string to pre-populate existing shapes on the map (when **Save as Content Document** is not active).
* **Toolbar** — choose which drawing tools appear: Line, Polygon, Circle, Marker, Edit, Delete.
* **Toolbar Position** — places the toolbar at a map corner: Bottom Right (default), Bottom Left, Top Right, Top Left.
**Saving drawings as files**
Enable **Save as Content Document** to persist drawings as a Salesforce ContentDocument (file). When active:
* **Auto Save Content Document** — saves automatically without a button click.
* **Content Document Id** — provide an existing ContentDocument Id to update it instead of creating a new one.
* **Content Document Title** — the file title (default: "Avonni Map Drawing Document").
* **Content Document Linked Entity Id** — the record Id to link the file to.
* **Save Button Label** — the label on the manual save button (default: "Save").
### Header
Adds a title bar above the map for labeling and header-level actions.
* **Title** — the heading displayed in the header.
* **Caption** — a smaller label displayed above the title.
* **Avatar** — optionally display an image or icon in the header. Set an **Image** URL, a **Fallback Icon Name**, or **Initials**. Size and variant (Circle or Square) are available under advanced options.
* **Help Text** — a hoverable icon that displays supplementary information.
* **Is Joined** — removes the header's bottom border and shadow so it sits flush against another component beneath it.
* **Actions** — add header-level buttons. Each action has a **Label**, **Name**, **Icon Name**, and optional **Disabled** / **Hidden** toggles.
* **Visible Actions Buttons** — the number of action buttons shown directly in the header before the rest overflow into a menu.
* **Hide Actions** — hides all header action buttons.
* **Disable Actions** — disables all header action buttons without hiding them.
* **Show More Details Panel** — enables a side panel that displays additional record details when a marker is selected.
### Popup *(Leaflet only)*
* **Width** — sets the width in pixels of the popup that appears when a user clicks a marker.
### Image *(Leaflet only)*
Configures an image displayed in each list-view item alongside the marker information.
* **Image Fallback** — a fallback image URL shown when the item's image fails to load.
* **Position** — where the image sits relative to the list item content: Left (default), Right, Top, Bottom, or Background.
* **Size** — predefined image size: Small, Medium, or Large. Controls width for Left/Right positions and height for Top/Bottom/Background.
* **Width** — custom pixel width. Applies only to Left and Right positions; overrides **Size**.
* **Height** — custom pixel height. Applies only to Top, Bottom, and Background positions; overrides **Size**.
* **Crop Fit** — how the image fills its container: Cover (default), Contain, Fill, or None.
* **Crop Position X / Y** — fine-tune the image anchor position as a percentage along each axis.
### Filter
Adds a filter menu so users can narrow down the markers displayed on the map. The fields available as filters are configured in the **Data Source** fields list.
* **Type** — where the filters are displayed: **Horizontal** (default, inline above the map), **Popover** (a floating popover opened from a filter button), or **Panel** (a collapsible side panel beside the map).
* **Use Record Picklist Values** — when enabled and filtering a picklist field, derives filter options from values present in the loaded records rather than the field's full defined value set.
* **Use Cascading Filter Values** — when a filter is applied, dynamically narrows the available options in other filters to reflect only records matching the current selection. Overrides **Use Record Picklist Values**.
### Search
Adds a search bar to let users find specific markers by text.
* **Show Search** — enables the search bar.
* **Placeholder** — the placeholder text shown in the search input (default: "Search"). Requires **Show Search**.
* **Position** — where the search bar appears: Left (default), Right, Center, or Fill. Requires **Show Search**.
### Set Component Visibility
All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).
## Interactions
[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Map. Configure them from the **Interactions** tab of the Edit Map panel.
### Marker Select
Fires when a user clicks a marker on the map. The **selectedMarker** output is populated with the clicked marker's data (title, description, location, and value), and **selectedMarkerSObject** is populated with the related Salesforce record when a query or variables data source is used.
### Header Action Click
Fires when a user clicks one of the custom action buttons in the map's header. Use the **targetName** output to identify which action was clicked and branch your flow logic accordingly.
### Drawing Created *(Leaflet only)*
Fires each time a user completes a new drawing on the map using the drawing toolbar. Use this to capture the updated GeoJSON output and store or process the drawn shape.
### Marker Created *(Leaflet only)*
Fires when a user places a new marker on the map using the drawing toolbar. The **createdMarker** output is populated with the new marker's latitude and longitude.
### Save As Button Click *(Leaflet only)*
Fires when the user clicks the manual save button to persist drawings as a Salesforce ContentDocument.
## Output Variables
The Map exposes several output variables you can reference elsewhere on the page after the user interacts with it — for example, in another component's configuration or a page formula.
### Marker Selection
When a user clicks a marker, these variables update with the selected marker's data.
| Output variable | Type | What it returns |
| ---------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Selected Marker** | Object | The selected marker's data — its value, title, description, and location (Latitude, Longitude). |
| **Selected Marker SObject** | Record (SObject) | The full Salesforce record associated with the selected marker. Requires a **Query** or **Variable** data source. |
| **Selected Markers sObject** | Record Collection (SObject\[]) | The Salesforce records for all selected markers when multi-select is enabled. Requires a **Query** or **Variable** data source. |
> **Example:** When a user clicks a marker on an Account map, use **Selected Marker SObject** to show the Account's details in a record-detail component beside the map.
### Marker Creation *(Leaflet only)*
When a user creates a new marker with the drawing tools, this variable captures its position.
| Output variable | Type | What it returns |
| ------------------ | ------ | ------------------------------------------------ |
| **Created Marker** | Object | The new marker's location (Latitude, Longitude). |
### Drawing Tools *(Leaflet only)*
| Output variable | Type | What it returns |
| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ |
| **Draw Tools Serialized** | Text (String) | The shapes drawn on the map as a serialized JSON string. Use it to persist the drawn area to a record. |
### Header Actions
| Output variable | Type | What it returns |
| ------------------------------ | ------------- | ------------------------------------------------------ |
| **Clicked Header Action Name** | Text (String) | The name of the header action button the user clicked. |
### Others
| Output variable | Type | What it returns |
| ---------------------- | ------- | --------------------------------------------------------------------- |
| **Number of Items** | Integer | The total number of markers currently loaded on the map. |
| **Visible Width (km)** | Integer | The visible width of the map in kilometers at the current zoom level. |
---
# 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/dynamic-components/components/map.md?ask=&goal=
```
`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.