From ideal-postcodes
Use this skill whenever the user wants address autocomplete, address suggestions as the user types, address validation in a form, UK address lookup, or any form field that should be auto-populated from a selected address — even if they don't name the package. Specifically covers `@ideal-postcodes/address-finder`. Includes npm and CDN install, initialisation via `AddressFinder.setup` / `AddressFinder.watch` (React), callbacks, CSS, country filter/bias, and common gotchas (API key allowed-URLs, bundled vs source build, CSS import).
How this skill is triggered — by the user, by Claude, or both
Slash command
/ideal-postcodes:ideal-postcodes-address-finderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Address autocomplete widget for the Ideal Postcodes API. Suggests addresses as the user types and populates form fields when one is selected.
references/additional-data.mdreferences/bias-by-geolocation.mdreferences/bias-by-ip.mdreferences/bias-by-postcode.mdreferences/callbacks.mdreferences/configuration-reference.mdreferences/configure.mdreferences/convert-iso-code.mdreferences/css-classes.mdreferences/default-country.mdreferences/default-styling.mdreferences/detach-reattach-af.mdreferences/filter-by-country.mdreferences/filter-by-geospatial-box.mdreferences/filter-by-locality.mdreferences/filter-by-postcode-outward.mdreferences/hide-toolbar.mdreferences/hide.mdreferences/home.mdreferences/how-it-works.mdAddress autocomplete widget for the Ideal Postcodes API. Suggests addresses as the user types and populates form fields when one is selected.
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.
<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>
Use AddressFinder.watch (not .setup) inside useEffect — it will pick up the input field once it mounts. See react.md.
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.@latest will silently break when a major bumps. Use @ideal-postcodes/address-finder-bundled@4 (or whatever current major).@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.https://example.com, no trailing slash, no path).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.@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.
The references below are organised by intent. Read only the ones relevant to the user's task — not the whole list.
npm.md — npm/bundler install, source vs bundled trade-offsscript.md — CDN <script> tag installconfigure.md — minimum required config (apiKey, outputFields)configuration-reference.md — full options referencecallbacks.md — onAddressRetrieved, onLoaded, onCheckFailed, etc.react.md — AddressFinder.watch + useEffect patterndetach-reattach-af.md — re-mount on route changenudge-address-finder.md — manual re-init / re-attachrestrict-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 restrictCountriesdefault-country.md — pre-select / bias toward a countryfilter-by-country.md — filter results by countryconvert-iso-code.md — ISO 3166 helperfilter-by-locality.md — by post townfilter-by-postcode-outward.md — by outward postcodefilter-by-geospatial-box.md — within a bounding boxbias-by-postcode.md — toward a postcodebias-by-geolocation.md — toward a lat/lngbias-by-ip.md — toward the user's IP locationdefault-styling.md — built-in lookcss-classes.md — class hooks for custom CSSstyle-js.md — programmatic stylingmessages.md — customise UI stringssingle-field.md — one input that captures the whole addressseparate-input.md — dedicated finder input separate from output fieldsmultiple.md — more than one finder on the pagehide.md — hide output fields until an address is pickedprevent-autofill.md — disable browser autofill on finder inputkey-usability.md — keyboard navigation tweaksadditional-data.md — populate fields beyond the standard 5 linesomit-organisation.md — strip organisation name from line 1tag-resolve.md — tag-based address resolutionhow-it-works.md — internal model: input field, dropdown, key checktroubleshooting.md — common errors with root cause + fix (authored sibling, not in references/)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.
npx claudepluginhub ideal-postcodes/skills --plugin ideal-postcodesCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.