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)

```html
<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.

ideal-postcodes-address-finder

Address Finder

Quick Start (npm + bundler)