Input form control

Map

<ut-map>

Shows an address or coordinates from another field on an OpenStreetMap map, and can let people drop a pin to record a location.

Uses OpenStreetMap

Officialv1.0.0
Download .utpkg 63 KBInstall in your workspace

Try it

Live preview

The real control in the same sandboxed frame the app uses. Switch to dark mode or read-only to see how it adapts.

Site location

Click the map to move the pin. Map data © OpenStreetMap contributors.

Value the form receives

{
  "lat": -36.844149,
  "lng": 174.76716
}

Sandboxed frame (opaque origin, its own CSP), talking to this page only through the typed postMessage bridge — exactly as on a form.

About

What it does

A map for any form that deals with places: a site visit, a delivery drop-off, a fault report, an event venue. Map it to an Address field (or any field holding coordinates or "lat,lng" text) and it centres on that location with a pin, following the field as it changes.

Turn on "Let people drop a pin" and the map becomes an input: click or tap the map, drag the pin, or type exact coordinates, and the field stores { lat, lng }. Keyboard users Tab to the map, pan with the arrow keys, zoom with + and -, and press Enter to drop the pin at the centre (a crosshair marks it).

Tiles come from OpenStreetMap (dimmed to match dark mode, or always light). The frame fetches them itself and draws them from memory, so nothing but the approved tile hosts is contacted. Attribution is always shown.

Good for

  • Show where a chosen address is, next to an Address field
  • Record the exact spot of a fault, hazard or delivery drop-off
  • Confirm a site location on an inspection or field-service task

After installing

  1. Install the package: the control appears in Extensibility → Form controls and in the form designer's palette under Custom.
  2. Approve the tile hosts in Extensibility → Form controls → Map: tile.openstreetmap.org. Until then the map shows the pin on a plain background and says which host to approve.
  3. Drag Map onto a form and map its Location to the field it should show (for example an Address field), or leave it unmapped and turn on "Let people drop a pin".
  4. Choose the map style, zoom, height and whether coordinates are shown in the properties panel.

Reference

Value, properties and accessibility

Value

{ lat: number, lng: number }

Stored as the field's value (type json), validated by the server against the control's schema; the control also reports its own validity while people type.

Read-only views (completed tasks, mobile, emails) show {{value.lat}}, {{value.lng}}.

Keyboard and screen readers

Role: application, named by the field label.

Tab to the map: arrow keys pan, + / - zoom. With pin dropping on, Enter or Space drops the pin at the centre (a crosshair marks it). The Latitude and Longitude inputs set the pin exactly; Clear removes it.

Properties (set in the form designer)
PropertyTypeDefaultWhat it does
Map style tilesOpenStreetMap, dimmed in dark mode / OpenStreetMap, always lightauto
Zoom zoomnumber 1–19151 shows the world, 15 a few streets, 19 a building.
Map height (px) heightnumber 160–800320
Let people drop a pin pickbooleannoClick, tap or press Enter to place the pin; the field stores its coordinates. Off: the map only shows the location.
Show coordinates show_coordinatesbooleanyesLatitude and longitude under the map (editable when people can drop a pin).

Context (other fields it reads)

  • location — Location: The field to show on the map: an Address field, coordinates ({lat, lng}) or "lat,lng" text. The map centres on it and shows a pin.

The designer maps each one to a field of the same form; the control receives those values read-only.

Capabilities and security

Network
Fetches only from the hosts in its manifest, and only after an administrator approves them in Extensibility → Form controls. Until then the frame's CSP blocks every request. Map tiles come through the UserTasks server (public tile servers refuse the sandboxed frame's referrer-less requests), only once the tile host is approved. Hosts: tile.openstreetmap.org.

Install

Install it in your workspace

Works on UserTasks cloud and any self-hosted instance. The control lands in Extensibility → Form controls, enabled, and appears in the form designer's Custom palette.

In the app

  1. Open Extensibility → Form controls → Browse gallery (it opens Packages → Browse gallery on the Form controls tab) and choose Install on Map. Or download form-control-map-1.0.0.utpkg and drag it onto Automations → Packages.
  2. The wizard verifies the checksum, every file hash and the signature, and shows what it adds.
  3. In Extensibility → Form controls, an administrator approves tile.openstreetmap.org.
  4. Drag the control onto a form in the designer and set its properties.

With the CLI

shell
curl -fLO https://usertasks.com/gallery/form-control-map-1.0.0.utpkg
usertasks packages inspect form-control-map-1.0.0.utpkg
usertasks packages install form-control-map-1.0.0.utpkg

Verify the download

File SHA-256
0cd399cd8b76dc4d0004d9a3a33f8922d40741927b9e6009fc562cc560e5ae6b
Package checksum (what is signed)
sha256:253c0e11b94fb126fe3a89e2aad37b90df7c74beefd93fd0c2148ff65a3e0d5e
<ut-map> module SHA-256
eeb6bd6b75a81efdcd841a99eee5f06d20d04cc0aef97ee82d1ad025be3556e5
Signer
UserTasks Gallery · 49:f3:04:90:47:02:4d:07:28:61:3d:dc:bb:aa:db:11

More form controls

All controls