Address autocomplete

Embed the widget

Add labelled fields and this script to your page. Replace YOUR_KEY with your account key. The widget waits 150 ms after typing and searches from three characters.

<label for="address">Find an address</label>
<input id="address" type="text" maxlength="200">
<label for="street">Street address</label>
<input id="street" name="line1">
<label for="postcode">Postcode</label>
<input id="postcode" name="postcode">
<script src="https://yepthere.au/widget.js" defer
  data-key="YOUR_KEY" data-input="#address"
  data-fields='{"line1":"#street","postcode":"#postcode"}'></script>

For JavaScript setup, call Yepthere.attach(inputElement, { key, baseUrl, fields, limit, onSelect }) after the script loads. The default limit is six, capped at twenty. The default base URL is the script origin. Use data-base-url and data-limit for the same options in HTML.

Map your fields

Map record names to CSS selectors or input elements. The widget clears missing values and dispatches input and change events. Keep postcodes as text.

{
  "line1": "#widget-line1",
  "line2": "#widget-line2",
  "suburb": "#widget-suburb",
  "state": "#widget-state",
  "postcode": "#widget-postcode",
  "latitude": "#widget-latitude",
  "longitude": "#widget-longitude",
  "uprn": "#widget-uprn"
}

The input emits a bubbling sa:select event with the complete record in event.detail, including boundaries when available. The onSelect(record) callback receives the same record after the fields are filled. Call the returned destroy() method before removing the form.

Theme it

The widget inherits your font. Set these CSS properties on a parent of the input or on .sa-widget. Keep text and keyboard focus easy to see.

Keyboard and screen readers

Give the search input a visible label. Arrow keys move through matches, Home and End jump to the first or last match while the list is open, Enter selects, Escape closes, and Tab leaves the input. Focus stays on the input while a screen reader follows the active option. Status messages announce matches and failures. Options have a minimum height of 44 pixels, and the widget respects reduced motion.

Keys in the browser

Use a browser key (prefix sab_live_) from your account page: it only works from the websites you list, only for lookups, and at 5 requests a second. Anyone who views the page source can read it, which is why those limits exist. A server key pasted into a page would expose its full allowance, so keep server keys on the server. The widget sends the key in the x-api-key header, never in the request URL, and does not log or persist it. Never embed the trusted system key.

Self-hosting and attribution

Copy src/widget/widget.js to your static assets, serve it as text/javascript, and set baseUrl or data-base-url to the address service. No build step or dependencies are needed. Allow the script, its injected styles and connections to the API in your site's content security policy.

Keep the widget attribution visible. Incorporates or developed using G-NAF © Geoscape Australia licensed by the Commonwealth of Australia under the Open Geo-coded National Address File (G-NAF) End User Licence Agreement. Do not use this data to compile a list for sending mail without verification from a secondary source.