Addresso Widget

Drop-in UK address lookup widget for any website. One script tag — no framework required.

Usage

HTML (data attributes)

<div id="addresso" data-api-key="ak_your_api_key"></div>
<script src="https://unpkg.com/@addresso/widget"></script>

<script>
  document.getElementById("addresso").addEventListener("addresso:select", function (e) {
    console.log(e.detail); // full address object
  });
</script>

JavaScript API

<div id="address-lookup"></div>
<script src="https://unpkg.com/@addresso/widget"></script>

<script>
  Addresso.init({
    target: "#address-lookup",
    apiKey: "ak_your_api_key",
    placeholder: "Enter postcode",
    buttonText: "Find address",
    onSelect: function (address) {
      console.log(address.building_number, address.street);
      console.log(address.town, address.postcode);
    },
  });
</script>

Options

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your Addresso API key | | target | string/Element | — | CSS selector or DOM element to mount into | | baseUrl | string | https://addresso.co.uk | API base URL | | placeholder | string | "Enter postcode" | Input placeholder text | | buttonText | string | "Find address" | Button label | | onSelect | function | — | Called with the full address object when selected |

Events

When using data attributes, listen for the addresso:select custom event on the container element. The event.detail contains the full address object.

Address object

The address object contains: postcode, town, locality, sub_locality, street, secondary_street, building_number, building_name, sub_building, po_box, department, organisation, udprn, postcode_type, delivery_point_suffix, latitude, longitude.

Styling

The widget ships with minimal built-in styles using .addresso-widget__* classes. Override them in your own CSS to match your site's design.

License

MIT