> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postcode.gov.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Web embed

> Embed the postcode widget in any website with @nipost/postcode-widget.

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

```bash theme={null}
npm install @nipost/postcode-widget
```

```html theme={null}
<script src="https://widget.postcode.gov.ng/sdk.js"></script>
```

## Usage

```js theme={null}
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`](/widget/overview#the-selection-payload) — 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.