> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/library/ui-components/map.md).

# Map

The **Map** component is an interactive component supporting multiple layer types. It defaults to OpenStreetMap as the bottom layer if nothing else is defined.

{% hint style="info" %}
Showroom: [Map example](https://showroom.appfarm.app/ui-components/map) and [Get current location example](https://showroom.appfarm.app/use-cases/get-current-location), with their setup in Appfarm Create ([register](https://showroom.appfarm.app/sign-up) for access).
{% endhint %}

## Properties

### Disabled

Set to `true`, or bind it to a boolean value, to disable the map.

### Initial Latitude, Longitude and Zoom

You may bind the settings **Initial Latitude** and **Initial Longitude** to properties in your data holding the GPS coordinates for the position you want to map to open as default centered.

This setting is optional. Without this setting, the map will try to center the map based on the markers (as defined by the Layers, see further down).

You may also override the Initial Zoom if you want a more focused initial zoom for your map. Initial Zoom defaults to 15.

### Max Zoom

The highest zoom level the user can zoom in to. Defaults to 19.

### Current Latitude, Longitude and Zoom

The current latitude, longitude and zoom level can be bound to properties in your data model. These properties are two-way data bound.

Upon panning and zooming, the center coordinates of the map and current zoom level will be written to these properties. If any of these properties are updated outside of the map, for example using a separate UI component, the map will update accordingly.

### Fit Selected Bounds

If `true`, the map automatically fits to the bounds of the selected data. Defaults to `false`.

### Write Click Coordinates

If this setting is selected, you may bind the **Click Latitude** and **Click Longitude** to properties in your data. Each click will write the coordinates back to those properties.

### Use Default Map

Default checked, meaning OpenStreetMap will be the map provider. If unchecked, you may add another map source (such as Mapbox) as a map provider. This is done by adding a new *Layer* of type *Map*.

### Zoom Control

Default checked. Buttons for zooming in and out will be visible in the map when this option is enabled.

### Prevent Touch Default

When panning a map on a mobile device: If the map is placed inside a UI component that is reacting to the same touch movements, you may get some undesired behaviour. For example, when a map is placed inside a bottom drawer, the drawer may close while panning the map vertically. You may prevent these defaults by enabling Prevent Touch Default, and the map will own these events when panning inside the map.

### Event Handlers

The map has an **On Click** event, which runs when the map is clicked, and an **On Zoom** event, which runs when the map is zoomed. Markers layers also have their own **On Click** event (see below).

### Layers

You may add different layers to your map by adding **Layers**. You may have multiple layers. The **Layer Type** can be Map, Static GeoJSON, Data GeoJSON, Markers or WMS.

#### Layer Type: Markers

Add Markers to your map.

**Data Source**

You will need a data source holding longitude and latitude for the objects you want to add to the map. Select this data source in the **Data Source** setting, and more settings will appear.

**Latitude and Longitude**

Select the properties of your Data Source holding the latitude and longitude for the marker to be displayed.

**Selection, Filter and Limit**

Shown when the **Data Source** holds many objects.

* **Selection**: Which objects to show: All objects (default), Selected object(s), Object in context or Filtered selection.
* **Filter**: Shown when **Selection** is Filtered selection. The filter that picks the objects to show.
* **Conditional Filters**: Filters that apply only while their condition is true.
* **Limit**: The maximum number of markers to show.

**Popup text**

When the marker is clicked, display a popup. The popup text is shown as plain text. Select **Markdown** to format it with markdown. HTML in the text is shown as text, also when **Markdown** is selected.

**Tooltip**

Displayed when hovering a marker. The tooltip is shown as plain text, so HTML in it is shown as text.

**Permanent**

Only available when Tooltip is selected. Sets the tooltip as always visible.

**Icon and Icon Color**

Select an icon to be displayed as a marker (instead of the default pin), as well as the color for this. Use **Icon Value** and **Icon Color Value** to set the icon and color from data.

**Icon Image, Icon Size, Icon Anchor Origin and Icon Rotation Angle**

Use an image as the marker with **Icon Image**, set its **Icon Size** in px (default 56), choose which point of the icon is placed on the coordinate with **Icon Anchor Origin** (default Bottom Center), and rotate it with **Icon Rotation Angle**, an integer from 0 to 360 (default 0).

**Cluster Color**

Assign a theme color to clusters. Defaults to Primary.

**Clustering**

By default (**On**), if many markers are to be displayed, nearby markers will be clustered together. Select **Off** to turn clustering off, or **Off at Zoom Level** to stop clustering from the **Zoom Level** you set.

**Property Conditions**

You may display different icons or icon colors, based on different conditions.

**On Click**

Select an action to be executed when a marker is Clicked

#### Layer Type: Data GeoJSON

You may add polygons for defining sections, or lines for defining borders or lines/paths.

Select a **Data Source** holding the polygon(s) or line to be displayed, and select the property holding the polygon in the **Data** setting.

Style the shapes with **Color** or **Color Value**, and set **Selected Border Color**, **Selected Fill Color**, **Hover Border Color** and **Hover Fill Color**.

Shapes are filled with the line color. Set **Fill Opacity** (default 0.2) to make the fill lighter or stronger. **Selected Fill Color** fills selected shapes with a solid color.

A polygon data property may be of the following format (example with 1 polygon). The polygon GPS coordinates should be replaced with the long/lat variables:

{% code collapsedlinecount="10" %}

```
{
"type": "FeatureCollection",
"features": [
{
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [long1,lat1],[long2,lat2],[long3,lat3]
          ]
        ]
      },
      "properties": {
        "prop0": "value0",
        "prop1": { "this": "that" }
      }
    }
]
}
```

{% endcode %}

The data property for defining a Line may be of the following format. The line GPS coordinates should be replaced with the long/lat variables:

{% code collapsedlinecount="10" %}

```
{
"type": "FeatureCollection",
"features": [
{
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [long1,lat1],[long2,lat2],[long3,lat3]
        ]
      },
      "properties": {
        "prop0": "value0",
        "prop1": { "this": "that" }
      }
    }
]
}
```

{% endcode %}

#### Layer Type: Static GeoJSON

Set **File** to the GeoJSON to be displayed: a URL to an external resource, or a resource file.

#### Layer Type: Map

Set **File** to the URL of an external map provider (or a resource file). Use **Attribution** for the credit text shown on the map.

Example for Mapbox (you will need to set up your own Mapbox account):\
`https://api.mapbox.com/styles/v1/<YOUR_USER_NAME>/ckkybknqd1cvu17odf1s3ji59/tiles/256/{z}/{x}/{y}@2x?access_token=<YOUR_ACCESS_TOKEN>`

#### Layer Type: WMS

Add a layer from a Web Map Service. Set the service **URL**, the **Layers** to request, and check **Transparent** to request the layer with a transparent background.


---

# 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.appfarm.io/library/ui-components/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.
