Widget

Drop-in UK address lookup for any website. One script tag — no framework, no build step, no dependencies.

Quick start

Add the script and a container element. That’s it.

html

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

HTML setup

The widget auto-initialises on any element with id="addresso" or a data-addresso attribute. Configure via data attributes.

html

<div
  id="addresso"
  data-api-key="ak_your_api_key"
  data-placeholder="Type your postcode"
  data-button-text="Search"
></div>
<script src="https://unpkg.com/@addresso/widget"></script>

<script>
  document.getElementById("addresso")
    .addEventListener("addresso:select", function (e) {
      var address = e.detail;
      console.log(address.building_number, address.street);
      console.log(address.town, address.postcode);
    });
</script>

JavaScript API

For more control, use Addresso.init() instead of data attributes.

html

<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) {
      document.getElementById("street").value = address.street;
      document.getElementById("town").value = address.town;
      document.getElementById("postcode").value = address.postcode;
    },
  });
</script>

Options

Pass these to Addresso.init() or use the equivalent data-* attributes.

apiKeystringrequired

Your Addresso API key. HTML: data-api-key.

targetstring | Elementrequired

CSS selector or DOM element to mount into. Not needed for data-attribute mode.

baseUrlstring

API base URL. Defaults to https://addresso.co.uk. HTML: data-base-url.

placeholderstring

Input placeholder. Defaults to "Enter postcode". HTML: data-placeholder.

buttonTextstring

Button label. Defaults to "Find address". HTML: data-button-text.

onSelectfunction

Called with the full address object when a user picks an address.

Events

In data-attribute mode, listen for the addresso:select custom event on the container. The full address object is in event.detail.

javascript

document.getElementById("addresso")
  .addEventListener("addresso:select", function (e) {
    var address = e.detail;
    // address.postcode, address.town, address.street, etc.
  });

Styling

The widget includes minimal built-in styles. All elements use .addresso-widget__* BEM classes that you can override in your own CSS.

css

/* Example: match your site's brand colour */
.addresso-widget__btn {
  background: #4F46E5;
}
.addresso-widget__btn:hover {
  background: #4338CA;
}
.addresso-widget__input:focus {
  border-color: #4F46E5;
  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.12);
}