Web embed - Postcode

Install the SDK, or drop the CDN script into your page:

npm install @nipost/postcode-widget

<script src="https://widget.postcode.gov.ng/sdk.js"></script>

Usage

import { PostcodeWidget } from "@nipost/postcode-widget";

const selection = await PostcodeWidget.open({
  key: "nipost_pk_live_…",
  identifierType: "email",        // or "nin"
  identifier: "ada@example.com",  // optional — omit to let the user type it
  onSelect: (s) => console.log("picked", s.formatted),
});

if (selection) {
  form.postcode.value = selection.formatted;
}

open() overlays a modal iframe hosted at widget.postcode.gov.ng, runs the whole flow inside it, and resolves with the PostcodeSelection — or null if the user dismissed the widget.

Options

Option	Type	Notes
`key`	`string`	Required. Your publishable key.
`identifierType`	`"nin" \| "email"`	Which identifier your integration uses. Default `"email"`.
`identifier`	`string`	Pre-fills the identity screen and skips it.
`widgetUrl`	`string`	Override the widget host (self-hosted / staging).
`onSelect`	`(s: PostcodeSelection) => void`	Fired before the promise resolves.
`onClose`	`() => void`	Fired when the user dismisses the widget.
`onError`	`(e: {code, message}) => void`	Session or network failures inside the widget.

Origins

The page embedding the widget must be listed in your publishable key’s allowed origins, or the widget will refuse to start. Add every production and staging origin when you create the key.