JavaScript Typeahead

Make any form field complete itself — a suburb, a town or city, or a postcode. It ships in the same package as the JavaScript Autocomplete, looks the same, and is free: it suggests plain values, not addresses, so it never spends a look-up. Macrons are optional when typing: "hawera" finds Hāwera.

Install from NPM or CDN

npm install getaddress-nz-autocomplete

<script src="https://cdn.getaddress.io/scripts/getaddress-nz-autocomplete-2.0.0.js"></script>

Usage

<label for="suburb">Suburb</label>
<input id="suburb" type="text">

<label for="town_city">Town or city</label>
<input id="town_city" type="text">

<label for="postcode">Postcode</label>
<input id="postcode" type="text">

<script>
    const token = '{your-domain-token}';

    // Each field completes on its own.
    getAddressNz.typeahead('suburb', token, { search: 'locality' });
    getAddressNz.typeahead('town_city', token, { search: 'town_city' });
    getAddressNz.typeahead('postcode', token, { search: 'postcode' });
</script>

From npm:

import { typeahead } from 'getaddress-nz-autocomplete';

typeahead('suburb', '{your-domain-token}', { search: 'locality' });

Events

input.addEventListener('getaddressnz-typeahead-suggestions', e => console.log(e.suggestions));
input.addEventListener('getaddressnz-typeahead-selected', e => console.log(e.value));

Options

Option	Default	What it does
search	all fields	The field this input completes — "locality", "town_city" or "postcode" — or an array of them. Unset, every field is completed alike.
filter	–	{ town_city, locality, postcode }, fixed for this field — e.g. { town_city: 'Auckland' } on a form that only takes Auckland addresses. A function is asked on every request. Blank values are ignored.
selected	–	Called with the value picked.
error	logs	Called when a request fails.
set_input_value	true	Write the picked value into the input.
min_characters	1	Characters before the first request.
debounce_ms	150	Quiet period before a request is sent. Left unset, it lengthens on a slow connection (up to 500). Set it to fix the delay.
max_suggestions	6	Maximum values shown. The API returns at most 20.
inject_styles	true	Inject the default stylesheet — the one the address widget uses.
class_names	–	Override the class names on the elements the widget creates.

Use a domain token, not an API key

Anything in browser JavaScript is readable by anyone who opens the page. A domain token is restricted to the domain you create it for, so publishing it costs you nothing. Create one in your console.