Map (Geospatial) Field

What This Feature Does

The Map field (sometimes called the Geospatial field) lets a form ask for geographic data — a precise point, a line drawn along a path, or an area marked as a polygon. Every shape (called a "feature") can be named, color-coded, and given its own attributes such as a description, photo, dropdown selection, or date.

Once a form is submitted, anyone with access can open the submission and see every feature drawn on a read-only map exactly as the field crew captured it.

Typical use cases

• Service locating: mark every located utility (gas, comms, power) with depth and photo
• As-builts: trace where pipework was installed, with materials and dimensions per segment
• Site inspections: drop a pin at each defect, attach a photo, log severity
• Compounds and exclusion zones: draw a polygon around the area, note dates and reasons
• Daily check-ins: capture the worker's location at the start of a job

Setting Up the Field (Form Builder)

The Map field is added like any other field type — drag it from the field palette, or click Add field → Map.

Configuration options

Allowed geometry types (required — at least one) Choose which shapes the form filler can draw:

• Point — a single map pin (typical for "where exactly is this thing?")
• Line — a multi-vertex line (typical for utility routes, fences, paths)
• Polygon — a closed area (typical for zones, compounds, work areas)

You can enable any combination. If your form only needs points, only enable Point — it makes the toolbar cleaner for the crew.

Custom base layer (optional) By default, the map uses a streets basemap. If a customer has supplied an aerial photo or site plan as a tile service, paste the XYZ URL here. The URL must contain {z}, {x}, and {y} placeholders (e.g. https://tiles.example.com/{z}/{x}/{y}.png). If the URL is invalid or unreachable at submission time, the field gracefully falls back to the default basemap.

Per-feature attributes These are the questions the form filler answers for each feature they draw. Click Add attribute and pick a type for each:

You can mark any attribute as Required — the form can't be submitted until every drawn feature has that attribute filled in.

Worked example

A service-locating form might be set up as:

• Allowed geometry types: Point + Line
• Attributes:
  • "Utility type" — Select with options "Gas / Comms / Power / Water"
  • "Depth (m)" — Number, required
  • "Photo" — Photo
  • "Notes" — Multi-line text

A crew filling this form drops a point for every located utility and traces a line for every run, filling in the four attributes per feature.

Filling in the Form (Field Crew)

When a form filler opens a published form with a Map field, they see an embedded map with a small toolbar in the top-left corner:

The toolbar only shows the buttons for geometry types the form builder enabled. The map supports two-finger pan/zoom on touch devices and standard scroll/drag on desktop. A fullscreen button in the top-right corner expands the map for precise drawing.

After drawing a feature

The moment a feature is finished (point dropped, line ended, polygon closed), an attribute panel slides in from the side (right on desktop, bottom on mobile). It contains:

1. Name — a free-text label. Defaults to "Feature 1", "Feature 2", etc., but the crew can rename to something meaningful like "Hydrant near gate" or "Compound A". If a name is set, it shows as a label on the map next to the feature.
2. Color — a curated palette of 8 colors. The chosen color tints the feature on the map in real time. Defaults to blue.
3. Attribute fields — one for each attribute the form builder configured. Required attributes are marked with a red asterisk.

The crew can:

• Click any other feature to switch to that feature's attribute panel
• Use the cursor mode to drag a point, reshape a line, or move polygon vertices
• Click the trash button to delete the selected feature

Use my location

If the field's geometry types include Point, a Use my location button appears in the toolbar. Tapping it:

1. Asks for location permission (first time only).
2. Drops a point at the device's GPS coordinates.
3. Stores the GPS accuracy (in metres) and the source (web-gps).
4. Pans the map to the captured point at zoom 17.

If location permission is denied, the device's GPS can't determine position, or it takes too long, an inline error appears on the toolbar explaining what happened. The crew can dismiss the error and either retry or fall back to clicking the map manually.

Submitting

The whole form (Map field plus all other fields) is submitted at once with the form's normal Submit button. Each drawn feature is saved as its own database row alongside the submission and its version. The data is durable — even when the crew rapidly toggles between drawing modes or hits Submit before the attribute panel closes, every feature with a finished geometry is captured.

Viewing a Saved Submission

When a teammate opens a submitted Map-field submission from the Submissions list, they see a read-only map showing every feature exactly as it was drawn:

• Each feature renders in its captured color
• Named features show their name as a label above the point / on the line / over the polygon
• The map auto-zooms to fit all features (single point → centered at zoom 16; multiple features → bounds-fit with a small padding)

Clicking any feature opens the attribute panel for that feature in read-only mode:

• Name and color are shown as a heading + small color dot
• Every attribute appears as a disabled field showing the captured value
• Photo attributes show a thumbnail; clicking the thumbnail opens the full-size preview
• The map and the toolbar are still visible behind the panel so you can navigate freely

In the Submissions table view, the Map column for each row shows the number of features that submission contains (e.g. "14 features") rather than the raw data.

Permissions and Visibility

Map features inherit the same visibility rules as the rest of the submission:

• Team members with forms.view can see submissions and their map features
• The owner / admin / member / manager roles all have this by default
• Customer / supplier / visitor portal users do not see form submissions in their portal navigation (their menu is scoped to invoices, purchase orders, or visitor-specific forms), so map features are not exposed to them in normal use

There are no additional permissions specific to the Map field — if a user can see the submission, they can see its features.

Troubleshooting (Support Notes)

"I can't see the map / the page just shows a spinner"

Usually one of:

1. Slow network — the basemap tiles are loaded from basemaps.cartocdn.com. On very slow connections this can take 10+ seconds. The page shows a small pulsing dots indicator while loading.
2. Custom base layer URL is unreachable — if the form builder set a custom base layer URL that's invalid or offline. The renderer falls back to the default basemap automatically, but the first load can stall briefly while the fetch fails. Confirm the custom URL is reachable from a browser.
3. Browser blocks the map domain — corporate firewalls sometimes block CDN domains. Test on a different network.

"I can't draw points / lines / polygons"

• Confirm the form builder enabled that geometry type on the field.
• Make sure the user has clicked the corresponding toolbar button (Pin / Line / Hexagon) — clicking the map in Select mode (the cursor button) doesn't draw anything; it tries to pick an existing feature.
• For line and polygon: the crew must click each vertex; clicking once doesn't finish a line. Closing a polygon requires clicking the first vertex again.

"Use my location doesn't work"

• Browsers require the page to be served over HTTPS for geolocation. In production this is always the case. On localhost it usually works in Chrome/Firefox, but some Safari builds block it.
• The user must grant location permission when prompted. If they previously denied, they need to clear the per-site permission in their browser settings.
• The error message on the toolbar identifies which of the three failure modes (denied / unavailable / timeout) occurred — pass that wording on when escalating.

"My photo didn't upload"

• The Photo attribute uses the same file-upload flow as the rest of Forms. A photo larger than 10 MB is rejected by the renderer.
• The photo must be an image MIME type (PNG, JPG, HEIC, etc.). Non-image files are rejected.
• Photos are stored against the submission's account, with the per-feature path. If the upload fails, the file just isn't attached — the submission itself still saves with the geometry intact.

"The submission saved but my features look wrong / are missing"

• Refresh the page once. The viewing page reads features fresh from the database — if there was a transient connectivity blip during the load, a refresh always fetches the canonical state.
• Older submissions (saved before name + color were a feature) will render in the default blue with their default "Feature N" labels. That's by design — the data is captured as it was at submit time.
• If features still appear missing after a refresh, capture the submission ID (visible in the URL when viewing the submission) and escalate. The features-per-submission relationship is enforced server-side, so a missing-feature report should be investigated.

"Form filler reports the screen jumped / scrolled while drawing"

Drawing a multi-vertex line or polygon doesn't require the page to scroll — but on small screens the attribute panel takes a slice of the screen when it opens. Suggest they tap fullscreen on the map (the maximise icon top-right) for more drawing space.

Known Limitations

• No offline support yet. A device with no connection can't load the basemap tiles, can't query the form schema, and can't save the submission. Crews working in remote areas must have signal at submission time. Offline capture is on the roadmap.
• No bulk reporting view yet. Plotting features across multiple submissions on a single map (per-form reporting) is a follow-up feature. Today, features are viewed one submission at a time.
• No GeoJSON / CSV export yet. Same follow-up as above.
• No native mobile support yet on the Expo app. The web form works on mobile browsers including in-app webviews, but a native drawing UI for the Expo build is in progress.

Related Features

• Field Types — full reference for every field type including the Map field
• Form Builder — how to add and configure fields
• Submissions — managing the captured data
• Permissions — controlling who sees submitted data