---
url: /en/docs/fields/map.md
description: >-
  Select geographic locations in Sveltia CMS with an interactive map and
  geolocation support.
---

# Map Field

The Map field type allows users to select geographic locations using an interactive map interface. It supports selecting single points, lines, or polygons, and stores the selected geometry as a GeoJSON string.

## User Interface

### Editor

An interactive map interface that enables users to select geographic locations visually by clicking on the map. The map supports zooming and panning for better precision. It also includes the following features:

* A search box to find locations by name or address.
* A button to center the map on the user’s current location using the browser’s [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API).
* A Clear button to remove the selected location(s).

The map UI is built with the [Leaflet](https://leafletjs.com/) and [Terra Draw](https://github.com/JamesLMilner/terra-draw) libraries, utilizing [OpenStreetMap](https://www.openstreetmap.org/) tiles and the [Nominatim](https://nominatim.org/) search API. You don’t need to set up any API keys to use those free services.

::: tip CSP

You may need to update your Content Security Policy (CSP) to allow loading map tiles and making search API requests. See the [CSP documentation](/en/docs/security#setting-up-content-security-policy) for more details.

:::

::: info Future Plans

We plan to add support for additional map providers in the future, such as Mapbox and Google Maps, to offer more customization options.

:::

### Preview

The data output, which is a GeoJSON string, is displayed. See below for details on the data format.

## Data Type

A stringified [GeoJSON](https://geojson.org/) object representing the selected geometry. Depending on the selected `type` option, the GeoJSON will be in one of the following formats:

```
{"type":"Point","coordinates":[lng,lat]}
```

```
{"type":"LineString","coordinates":[[lng1,lat1],[lng2,lat2],...]}
```

```
{"type":"Polygon","coordinates":[[[lng1,lat1],[lng2,lat2],[lng3,lat3],...]]}
```

You need to parse this string to work with the GeoJSON data in your application.

::: tip Coordinate Order

The coordinates are in the order of longitude first, then latitude, as per the GeoJSON spec. Some libraries use latitude-longitude order, so be cautious when integrating with other mapping tools.

:::

If the `required` option is set to `false` and locations are not selected, the value will be an empty string.

## Data Validation

* If the `required` option is set to `true`, a valid GeoJSON string must be provided.
* The GeoJSON string must conform to the specified geometry `type` (Point, LineString, or Polygon).
* Coordinates must be valid latitude and longitude values.

## Options

In addition to the [common field options](/en/docs/fields#common-options), the Map field supports the following options:

### Required Options

#### `widget`

* **Type**: `string`
* **Default**: `string`

Must be set to `map`.

### Optional Options

#### `default`

* **Type**: `string`
* **Default**: `""`

A default GeoJSON string to prepopulate the field. The string should be a valid GeoJSON representation of the selected geometry. The `type` option should match the geometry type of the default value.

#### `decimals`

* **Type**: `number`
* **Default**: `7`

Number of decimal places for coordinates. Higher values provide more precision but may increase the size of the stored data.

#### `type`

* **Type**: `string`
* **Default**: `Point`

Type of geometry to select. Supported values are:

* `Point`: Allows selecting a single location on the map.
* `LineString`: Allows drawing a line by selecting multiple points.
* `Polygon`: Allows drawing a polygon by selecting multiple points that form a closed shape.

#### `center`

* **Type**: `[number, number]`
* **Default**: `[0, 0]`

Default center coordinates of the map as `[longitude, latitude]`, following the GeoJSON coordinate order. This is used as the initial map view when no value is set. If a value already exists, the map centers on the stored geometry instead.

#### `zoom`

* **Type**: `number`
* **Default**: `2`

Default zoom level of the map when no value is set.

## Examples

### Basic Map Field

This example shows a simple Map field configuration, which allows users to select a single location on the map.

::: code-group

```yaml [YAML]
- name: location
  label: Location
  widget: map
```

```toml [TOML]
[[fields]]
name = "location"
label = "Location"
widget = "map"
```

```json [JSON]
{
  "name": "location",
  "label": "Location",
  "widget": "map"
}
```

```js [JavaScript]
{
  name: 'location',
  label: 'Location',
  widget: 'map',
}
```

:::

Output example:

::: code-group

```yaml [YAML]
location: '{"type":"Point","coordinates":[-122.4194015,37.7749144]}'
```

```toml [TOML]
location = '{"type":"Point","coordinates":[-122.4194015,37.7749144]}'
```

```json [JSON]
{
  "location": "{\"type\":\"Point\",\"coordinates\":[-122.4194015,37.7749144]}"
}
```

:::

### LineString Geometry with Decimals

This example shows a Map field configured to select a LineString geometry with a specified number of decimal places for coordinates.

::: code-group

```yaml{4-5} [YAML]
- name: route
  label: Route
  widget: map
  type: LineString
  decimals: 5
```

```toml{5-6} [TOML]
[[fields]]
name = "route"
label = "Route"
widget = "map"
type = "LineString"
decimals = 5
```

```json{5-6} [JSON]
{
  "name": "route",
  "label": "Route",
  "widget": "map",
  "type": "LineString",
  "decimals": 5
}
```

```js{5-6} [JavaScript]
{
  name: 'route',
  label: 'Route',
  widget: 'map',
  type: 'LineString',
  decimals: 5,
}
```

:::

Output example:

::: code-group

```yaml [YAML]
route: '{"type":"LineString","coordinates":[[-122.41940,37.77490],[-122.41800,37.77550]]}'
```

```toml [TOML]
route = '{"type":"LineString","coordinates":[[-122.41940,37.77490],[-122.41800,37.77550]]}'
```

```json [JSON]
{
  "route": "{\"type\":\"LineString\",\"coordinates\":[[-122.41940,37.77490],[-122.41800,37.77550]]}"
}
```

:::

### Default Center and Zoom

This example shows a Map field configured with a default center and zoom level, so the map opens in a specific region when no value is set.

::: code-group

```yaml{4-5} [YAML]
- name: location
  label: Location
  widget: map
  center: [-122.4194, 37.7749]
  zoom: 12
```

```toml{5-6} [TOML]
[[fields]]
name = "location"
label = "Location"
widget = "map"
center = [-122.4194, 37.7749]
zoom = 12
```

```json{5-6} [JSON]
{
  "name": "location",
  "label": "Location",
  "widget": "map",
  "center": [-122.4194, 37.7749],
  "zoom": 12
}
```

```js{5-6} [JavaScript]
{
  name: 'location',
  label: 'Location',
  widget: 'map',
  center: [-122.4194, 37.7749],
  zoom: 12,
}
```

:::