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", }, });


```html
<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)
additional-configuration.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/)

postcode-lookup

Postcode Lookup

Quick Start (npm + bundler)