ideal-postcodes-postcode-lookup

Postcode Lookup

Postcode search widget for the Ideal Postcodes API. User enters a UK postcode, picks an address from the dropdown, and your form fields auto-populate.

Quick Start (npm + bundler)

npm install @ideal-postcodes/postcode-lookup

import { PostcodeLookup } from "@ideal-postcodes/postcode-lookup";

const controller = PostcodeLookup.setup({
  apiKey: "ak_test",
  context: "#postcode-lookup-container",
  outputFields: {
    line_1: "#line_1",
    line_2: "#line_2",
    line_3: "#line_3",
    post_town: "#post_town",
    postcode: "#postcode",
  },
});

<div id="postcode-lookup-container"></div>

Quick Start (CDN / drop-in script)

<script src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/postcode-lookup-bundled@2"></script>
<div id="postcode-lookup-container"></div>
<script>
  IdealPostcodes.PostcodeLookup.setup({
    apiKey: "ak_test",
    context: "#postcode-lookup-container",
    outputFields: {
      line_1: "#line_1",
      line_2: "#line_2",
      line_3: "#line_3",
      post_town: "#post_town",
      postcode: "#postcode",
    },
  });
</script>

Critical Gotchas

• context is required. It tells the widget where to render its UI (search box, dropdown). Pass a CSS selector or DOM node. Without it, nothing appears.
• Use PostcodeLookup.setup({...}) — not new PostcodeLookup(...). It's a factory method, not a constructor.
• apiKey is camelCase, not api_key or API_KEY.
• Pin your CDN version in production. Pulling from @latest will silently break on a major. Use @ideal-postcodes/postcode-lookup-bundled@2 (or current major).
• Source vs bundled package: use @ideal-postcodes/postcode-lookup for bundlers. Use @ideal-postcodes/postcode-lookup-bundled for <script> tags or compatibility.
• API key allowed URLs. Frontend keys are restricted by domain. If requests fail with 403, add your domain at ideal-postcodes.co.uk/account — match scheme + host (e.g. https://example.com).
• Postcode normalization is automatic. The widget handles whitespace and case. Do not pre-format input.

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, context, outputFields)
• configuration-reference.md — full options reference
• callbacks.md — onAddressSelected, onLoaded, onSearchCompleted, etc.

React / single-page apps

• react.md — useEffect-based init pattern

Search behaviour

• full-search.md — enable address-text search alongside postcode (strictlyPostcodes: false)
• behaviours.md — fine-grained behaviour flags
• single-field.md — single combined input

Form patterns

• multiple.md — more than one postcode lookup on one page
• multi-page-form.md — populate fields across multiple form pages
• hide-fields.md — hide output fields until an address is picked
• remove-organisation.md — strip organisation name from line 1

Custom UI elements

• custom-input.md — replace the default postcode input
• custom-button.md — replace the default search button
• custom-elements.md — replace any rendered element
• add-custom-elements.md — inject extra UI (e.g. manual-entry link)
• custom-callback.md — drive selection from your own UI

Styling and UI

• css-classes.md — class hooks for custom CSS
• style-tweaks.md — common CSS overrides
• messages.md — customise UI strings

Address data

• additional-data.md — populate fields beyond the standard 5 lines

Concepts

• how-it-works.md — internal model: search → dropdown → populate

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.