@postio/address-finder

Drop-in UK address autocomplete. Accessible combobox over the Postio API.

This is the source package — for use with bundlers (Vite, Webpack, esbuild, Rollup, Next.js, etc.). For a script-tag drop-in with no build step, install @postio/address-finder-bundled or load from https://cdn.postio.co.uk/v1/address-finder.js.

Install

npm install @postio/address-finder

Use

<input id="address-search" />
<input id="address-line-1" />
<input id="town" />
<input id="postcode" />

import { setup } from "@postio/address-finder";

const finder = setup({
  apiKey: "pk_live_…",
  input: "#address-search",
  output: {
    address_line_1: "#address-line-1",
    post_town: "#town",
    postcode: "#postcode",
  },
});

// Later, if needed:
finder.clear();
finder.close();
finder.destroy();

Options

| Option | Type | Default | Notes | |---|---|---|---| | apiKey | string | — | Required. pk_* publishable key. | | input | string \| HTMLInputElement | — | Required. The text input the user types into. | | output | OutputMap | — | Required. Map of API field → DOM target to populate. | | baseUrl | string | https://api.postio.co.uk/v1 | Override for self-hosted / staging. | | bare | boolean | false | Skip the visual CSS layer; ship structural only. | | minLength | number | 2 | Min chars before searching. | | debounceMs | number | 80 | Debounce input by N ms. | | maxResults | number | 7 | Max suggestions in dropdown (cap 50). | | className | string | — | Extra class on the listbox element. | | zIndex | number | 1000 | z-index of the dropdown. | | onReady | () => void | — | Called once after setup. | | onSearch | (query, results) => void | — | After every search response. | | onSelect | (address) => void | — | When the user picks an address. Gets the full record. | | onError | (err) => void | — | Any search or fetch error. |

output keys are the API field names — address_line_1, post_town, postcode, county, udprn, latitude, longitude, etc. See @postio/api-types for the full list.

output values can be a CSS selector or an HTMLElement. <input>, <textarea> and <select> get their .value set + input and change events dispatched (so React/Vue/Angular pick up the change). Anything else gets .textContent set.

Theming

Default styling is intentionally minimal and inherits font + color from the parent. Override via CSS custom properties on any ancestor:

.my-form {
  --postio-af-bg: white;
  --postio-af-border: 1px solid #d0d4dc;
  --postio-af-radius: 6px;
  --postio-af-padding: 4px;
  --postio-af-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
  --postio-af-option-padding: 8px 10px;
  --postio-af-option-radius: 4px;
  --postio-af-option-hover-bg: #f3f4f6;
  --postio-af-focus-ring: 2px solid #2563eb;
  --postio-af-z: 1000;
}

Or target the BEM-style classes directly:

.postio-af__listbox { /* … */ }
.postio-af__option { /* … */ }
.postio-af__option[aria-selected="true"] { /* … */ }

For full control, opt out of visual defaults — setup({ ..., bare: true }) ships only the structural CSS (positioning, list semantics, hide/show).

Accessibility

• ARIA combobox pattern (WAI-ARIA 1.2): role="combobox" on the input, role="listbox" on the dropdown, role="option" per suggestion, aria-expanded / aria-controls / aria-activedescendant updated live.
• Full keyboard nav: ↑ / ↓ / Home / End / Enter / Escape / Tab.
• Mouse hover follows keyboard highlight.
• Inherits font-family, color, and font-size so it picks up the page's typography automatically.

Performance

• One in-flight search at a time — the previous one is aborted on the next keystroke.
• Free /connect warm-up fired on first input focus (no billing impact).
• Debounced input by default at 80 ms.

License

MIT.