Add Australian address autocomplete to a React app

18 July 2026 · 5 min read

You can add Australian address autocomplete to a React app without pulling in a heavy component library. There are two clean approaches: the drop-in widget, or calling the API directly from a small hook. Here’s both.

Option A: the drop-in widget

The widget is one script, no build step. Load it once and attach it to a ref. Use a publishable key locked to your domain, so it’s safe in the browser and can’t be used elsewhere.

import { useEffect, useRef } from 'react';

export function AddressField({ onPick }) {
  const ref = useRef(null);
  useEffect(() => {
    const s = document.createElement('script');
    s.src = 'https://api.wattleaddr.com.au/v1/widget.js';
    s.onload = () => {
      const wa = new window.WattleAddr('waddr_pk_live_…');
      wa.attach(ref.current, { onSelect: onPick });
    };
    document.body.appendChild(s);
    return () => s.remove();
  }, [onPick]);
  return <input ref={ref} placeholder="Start typing an address" />;
}

The widget manages session tokens for you, so all the keystrokes behind one address count as a single billable lookup.

Option B: call the API from your own component

If you want full control over the UI, call the endpoints yourself. Do the autocomplete from the browser with a publishable key, and do the billable retrieve from your backend with a secret key so it’s never exposed. Keep one session token for the whole interaction:

const session = crypto.randomUUID();
const res = await fetch(
  `https://api.wattleaddr.com.au/v1/addresses/autocomplete?q=${q}&session=${session}` ,
  { headers: { Authorization: `Bearer waddr_pk_live_…` } },
);
const { suggestions } = await res.json();

Handle the PO Box case

Whichever approach you pick, check the response for a notice. A PO Box returns an empty list with notice.code === "postal_address_unsupported" — show that message and offer a separate postal-address field rather than leaving the user with a blank dropdown.

Full types and every parameter are in the OpenAPI spec and the interactive reference, so you can generate a typed client instead of writing fetch calls by hand.