@locio-au/vue

@locio-au/vue

Vue address autocomplete for Australian addresses, with validation and geocoding built in. Backed by G-NAF, the national address register.

• An accessible combobox you can drop in, or a headless composable if you have your own template
• Debounced and cancelled properly, so typing an address costs one request rather than thirteen
• Every result is already resolved: a stable G-NAF id, a coordinate, an ABS mesh block and the address split into fields. No second call to find out what was picked.
• Vue 3, no dependencies beyond it

npm install @locio-au/vue

Quick start

<script setup lang="ts">
import { AddressAutocomplete, addressId, type Address } from "@locio-au/vue";

function onSelect(address: Address) {
  console.log(address.formatted);
  console.log(addressId(address)); // store this, not the text
  console.log(address.lat, address.lng);
  console.log(address.components?.postcode);
}
</script>

<template>
  <AddressAutocomplete
    public-key="lc_pub_..."
    label="Delivery address"
    @select="onSelect"
  />
</template>

That is the whole integration. It handles the debounce, cancels superseded requests, and implements the ARIA combobox pattern so arrow keys, Enter and Escape all work.

v-model binds the typed text if you want it:

<AddressAutocomplete v-model="typed" public-key="lc_pub_..." @select="onSelect" />

Use a public key

lc_pub_..., created at locio.com.au/account/api. A public key carries an origin allow list, so a copy lifted from your page does nothing anywhere else.

Never put a secret key (lc_live_...) in a page. Anyone who opens it can read the key and spend your quota. This package throws at construction if it sees a secret key in a browser rather than letting it reach production working perfectly.

For server code use locio (Python) or locio-go.

Styling

The default styles are deliberately minimal. Replace them with your own class names:

<AddressAutocomplete
  public-key="lc_pub_..."
  :class-names="{
    root: 'relative',
    input: 'w-full rounded-md border px-3 py-2',
    list: 'absolute z-10 w-full rounded-md border bg-white shadow',
    option: 'px-3 py-2 hover:bg-neutral-100',
    status: 'text-xs text-neutral-500',
  }"
/>

Or take the markup bare with :styled="false".

Headless

If you want your own template entirely, the composable has all the behaviour and no opinion about the DOM:

<script setup lang="ts">
import { useAddressAutocomplete, addressId } from "@locio-au/vue";

const { term, results, status } = useAddressAutocomplete({
  publicKey: "lc_pub_...",
  debounceMs: 300,
  minLength: 3,
});
</script>

<template>
  <input v-model="term" />
  <span v-if="status === 'searching'">Searching…</span>
  <span v-else-if="status === 'empty'">No addresses match that yet.</span>
  <span v-else-if="status === 'unavailable'">Lookup is unavailable.</span>
  <ul>
    <li v-for="a in results" :key="addressId(a)">{{ a.formatted }}</li>
  </ul>
</template>

Writing to term is what drives it, so it drops straight onto v-model.

status is one value rather than several booleans, because "searching" and "nothing found" being separately true is how a widget ends up claiming both. Note that empty and unavailable are different states: a widget that renders nothing for both tells the user neither, and an outage then looks exactly like an address that does not exist.

Address validation on its own

The client is exported if you want the other calls without the UI:

import { createClient, addressId } from "@locio-au/vue";

const locio = createClient({ publicKey: "lc_pub_..." });

const result = await locio.resolve("1 george st sydenham nsw 2044");
if (result.matched) {
  console.log(addressId(result.address!));
}

search, resolve and get cost one unit; similar costs three.

Where your visitor is

A public key is scoped to the country the visitor is in, which the service resolves from their own connection. Nothing in a page can widen that, and it is why the key is safe to publish.

So a visitor in a country we hold no addresses for gets no results and a sentence saying why, as an ordinary answer that costs nothing. Show that sentence rather than your own "nothing matched" message, which was written for somebody who has not typed enough yet:

const { results, status, note, countryCode } = useAddressAutocomplete({
  publicKey: "lc_pub_...",
});
// status === "empty" && note
//   -> "we hold no address data for NZ. Addresses are available for AU."

<AddressAutocomplete /> already does this: when the service explains itself, its message is the one shown. searchScoped and similarScoped on the client return the same three things without the UI.

Australia is what is covered today.

Which id to store

Read the id through addressId(address). It is the address's id in its country's register, and the one field every address carries:

An address outside Australia carries id and country_code and none of the G-NAF fields: no pid, no mesh_block, no gnaf object. They are absent rather than empty, because an empty one would say we hold something we do not. Ids are unique within a country, so store country_code beside the id.

import { isUnit } from "@locio-au/vue";

Storing the primary pid stores the building rather than the door, and nothing about the value itself says which you have.

Props and events

Accessibility

Implements the ARIA combobox pattern: role="combobox" with aria-expanded, aria-controls and aria-activedescendant; a role="listbox" of role="option"; arrow keys, Enter and Escape. The input is 16px, because anything smaller makes iOS zoom the page on focus.

Licence

MIT. Address data is G-NAF, published by Geoscape Australia under CC BY 4.0; attribution belongs wherever you show it.