Input form control

Address

<ut-address> <ut-map>

Address search with suggestions from Google Places (key kept on the server) or a data table, saved as street, city, postcode, country and coordinates.

Uses Google Maps Platform

Officialv1.0.0

Download .utpkg 84 KB Install 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 address

The preview answers every search with two sample Google Places results; on a form the suggestions come from your lookup source.

Value the form receives

null

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

An address field that finds the address for people instead of making them type it in five boxes. As they type, suggestions come from the field's lookup source: Google Places API (New) through an integration that keeps the API key on the UserTasks server, another geocoding API, or a data table of your own sites. Choosing a suggestion stores a structured address (street, city, region, postcode, country and country code) with its coordinates and place id, ready for workflows, reports and the Map control.

It is a standard ARIA combobox: Up and Down move through the suggestions, Enter chooses, Escape closes, and screen readers hear how many addresses were found. If an address can't be found, "Enter the address manually" shows separate street, city, region, postcode and country inputs.

The package includes the Google Places integration (you enter your API key when installing), the text search API reference and a sample form that pairs Address with a Map. The Map control ships in the same package so the sample works on its own; it stays offline until an admin approves its tile host (tile.openstreetmap.org) in Extensibility → Form controls.

Good for

Customer, delivery or billing address on a request form
Site address on an inspection or field-service task, shown on a Map
Choosing one of your own locations from a data table of sites or stores

After installing

In Google Cloud, enable Places API (New) and create an API key restricted to that API. It is a server key: the browser never sees it, so do not add a website (referrer) restriction.
Install the package and paste the key when asked: it is stored in the "Google Places API (New)" integration. The "Places text search (addresses)" API reference and the "Address and location (sample)" form come with it.
Use the sample form, or drag Address onto your own form and set its lookup source: API reference "Places text search (addresses)", query = {{search}}, results path places, display fields formattedAddress, addressComponents and location, value field id.
Optionally set a country hint (e.g. New Zealand), the placeholder and whether manual entry and the parsed details are shown. Add a Map control with its Location mapped to this field to show the address on a map.

Also in the package

Google Places API (New) (integration)
Places text search (addresses) (reference)
Address and location (sample) (form)

Reference

Value, properties and accessibility

Value

{ formatted: string, street: string | null, city: string | null, region: string | null, postcode: string | null, country: string | null, country_code: string | null, lat: number | null, lng: number | null, place_id: string | null }

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

Keyboard and screen readers

Role: combobox, named by the field label.

Type at least three characters to search. Down / Up move through the suggestions, Enter chooses one, Escape closes the list (a second Escape clears the field). "Enter the address manually" shows separate inputs.

Properties (set in the form designer)
Property	Type	Default	What it does
Placeholder `placeholder`	string	Start typing an address
Search after (characters) `min_chars`	number 1–20	3
Wait after typing (ms) `debounce_ms`	number 0–2000	350	How long to wait after the last keystroke before searching.
Allow manual entry `allow_manual`	boolean	yes	Shows "Enter the address manually": street, city, region, postcode and country inputs.
Show address details `show_details`	boolean	no	Shows the parsed street, city, region, postcode, country and coordinates under the field.
Country hint `country_hint`	string	—	Appended to every search as ", <country>" (e.g. New Zealand) to favour addresses in that country.

Capabilities and security

Lookups: Suggestions come from the field's lookup source — a data table, or an API reference the UserTasks server calls with credentials stored on the server. The control only sees the suggestions.
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

Open Extensibility → Form controls → Browse gallery (it opens Packages → Browse gallery on the Form controls tab) and choose Install on Address. Or download form-control-address-1.0.0.utpkg and drag it onto Automations → Packages.
The wizard verifies the checksum, every file hash and the signature, and shows what it adds.
Fill in Integration “Google Places API (New)” — stored encrypted on the server — or keep it incomplete and finish later.
In Extensibility → Form controls, an administrator approves tile.openstreetmap.org.
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-address-1.0.0.utpkg
usertasks packages inspect form-control-address-1.0.0.utpkg
usertasks packages install form-control-address-1.0.0.utpkg

Verify the download

File SHA-256: 948461f91112cc34b6517fcde03d002f7c9a4ee9127975e4adaef803a2b5df5e
Package checksum (what is signed): sha256:9c48dce565e9fba700dec0c8ecb3e52909444445f48bb7565a2067dd650604c5
<ut-address> module SHA-256: 69a1d55d7e94f444db063ca40a7b4eb78ce21e5e1e0fdd6f53c64298f8ab7780
<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