ideal-postcodes-address-finder

Address Finder

Address autocomplete widget for the Ideal Postcodes API. Suggests addresses as the user types and populates form fields when one is selected.

Quick Start (npm + bundler)

npm install @ideal-postcodes/address-finder

import { AddressFinder } from "@ideal-postcodes/address-finder";

const controller = AddressFinder.setup({
  apiKey: "ak_test",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});

If your bundler chokes on the source package, use @ideal-postcodes/address-finder-bundled instead — same API, pre-transpiled and polyfilled.

Quick Start (CDN / drop-in script)

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/address-finder-bundled"></script>
<script>
  IdealPostcodes.AddressFinder.setup({
    apiKey: "ak_test",
    outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      line_3: "#line_3",
      post_town: "#post_town",
      postcode: "#postcode",
    },
  });
</script>

React

Use AddressFinder.watch (not .setup) inside useEffect — it will pick up the input field once it mounts. See `react.md`.

Critical Gotchas

• Use `AddressFinder.setup({...})` — not `new AddressFinder(...)`. It's a factory method, not a constructor.
• `apiKey` is camelCase, not api_key or API_KEY.
• `outputFields` is required — it's the map from address attributes (line_1, post_town, postcode, …) to your form's input selectors. Without it, the widget has nothing to populate.
• Pin your CDN version in production. Pulling from @latest will silently break when a major bumps. Use @ideal-postcodes/address-finder-bundled@4 (or whatever current major).
• Source vs bundled package: use @ideal-postcodes/address-finder for bundlers (smaller, tree-shakable). Use @ideal-postcodes/address-finder-bundled for <script> tags or if your bundler can't handle the source package.
• API key allowed URLs. Frontend keys are restricted by domain. If requests fail with 403, check your key's allowed URL list at ideal-postcodes.co.uk/account — match scheme + host (e.g. https://example.com, no trailing slash, no path).
• Country toolbar vs country restriction are independent. restrictCountries: ["GBR"] removes the country picker control inside the toolbar — it does not hide the toolbar bar itself. For a clean single-country setup with no toolbar on focus, also set hideToolbar: true. See `hide-toolbar.md`.
• Bundler CSS import. The source package does not auto-inject CSS. Either import the stylesheet (@ideal-postcodes/address-finder/css/address-finder.css) or set injectStyle: true in the setup options.

For the long tail of error patterns and fixes, see `troubleshooting.md`.

When to read which reference

The references below are organised by intent. Read only the ones relevant to the user's task — not the whole list.

Setup and initialisation

• `npm.md` — npm/bundler install, source vs bundled trade-offs
• `script.md` — CDN <script> tag install
• `configure.md` — minimum required config (apiKey, outputFields)
• `configuration-reference.md` — full options reference
• `callbacks.md` — onAddressRetrieved, onLoaded, onCheckFailed, etc.

React / single-page apps

• `react.md` — AddressFinder.watch + useEffect pattern
• `detach-reattach-af.md` — re-mount on route change
• `nudge-address-finder.md` — manual re-init / re-attach

Country handling

• `restrict-country.md` — limit which countries the user can pick (removes the picker, not the toolbar bar)
• `hide-toolbar.md` — hide the toolbar bar entirely (hideToolbar: true); independent of restrictCountries
• `default-country.md` — pre-select / bias toward a country
• `filter-by-country.md` — filter results by country
• `convert-iso-code.md` — ISO 3166 helper

Filter / bias suggestions

• `filter-by-locality.md` — by post town
• `filter-by-postcode-outward.md` — by outward postcode
• `filter-by-geospatial-box.md` — within a bounding box
• `bias-by-postcode.md` — toward a postcode
• `bias-by-geolocation.md` — toward a lat/lng
• `bias-by-ip.md` — toward the user's IP location

Styling and UI

• `default-styling.md` — built-in look
• `css-classes.md` — class hooks for custom CSS
• `style-js.md` — programmatic styling
• `messages.md` — customise UI strings

Form layout patterns

• `single-field.md` — one input that captures the whole address
• `separate-input.md` — dedicated finder input separate from output fields
• `multiple.md` — more than one finder on the page
• `hide.md` — hide output fields until an address is picked
• `no-match-action.md` — offer an out (e.g. manual entry) when a search returns no matches (msgNoMatchAction + onNoMatchAction)
• `prevent-autofill.md` — disable browser autofill on finder input
• `key-usability.md` — keyboard navigation tweaks

Address data

• `additional-data.md` — populate fields beyond the standard 5 lines
• `omit-organisation.md` — strip organisation name from line 1
• `tag-resolve.md` — tag-based address resolution

Concepts

• `how-it-works.md` — internal model: input field, dropdown, key check

Troubleshooting

• `troubleshooting.md` — common errors with root cause + fix (authored sibling, not in references/)

Full documentation

The full Ideal Postcodes documentation — every guide, API reference, and integration — is available as a single file at llms.txt. Point your agent there for anything this skill doesn't cover.