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.
• A Clear button to remove the selected location(s).

The map UI is built with the Leaflet and Terra Draw libraries, utilizing OpenStreetMap tiles and the Nominatim search API. You don’t need to set up any API keys to use those free services.

CSP Settings

You may need to update your Content Security Policy (CSP) to allow loading map tiles and making search API requests. See the CSP documentation for more details.

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

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

Examples

Basic Map Field

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

YAML

- name: location
  label: Location
  widget: map

TOML

[[fields]]
name = "location"
label = "Location"
widget = "map"

JSON

{
  "name": "location",
  "label": "Location",
  "widget": "map"
}

JavaScript

{
  name: 'location',
  label: 'Location',
  widget: 'map',
}

Output example:

YAML

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

TOML

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

JSON

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

LineString Map Field with Decimals

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

YAML

- name: route
  label: Route
  widget: map
  type: LineString
  decimals: 5

TOML

[[fields]]
name = "route"
label = "Route"
widget = "map"
type = "LineString"
decimals = 5

JSON

{
  "name": "route",
  "label": "Route",
  "widget": "map",
  "type": "LineString",
  "decimals": 5
}

JavaScript

{
  name: 'route',
  label: 'Route',
  widget: 'map',
  type: 'LineString',
  decimals: 5,
}

Output example:

YAML

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

TOML

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

JSON

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