Web embed

Publication is pending: @nipost/postcode-widget is not on npm yet. That is how it will be installed; until then, build the SDK from sdks/widget-js in the gateway repository.

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

npm install @nipost/postcode-widget

<script src="https://unpkg.com/@nipost/postcode-widget@0.1.0/dist/sdk.js"></script>

The script build exposes the same API on a PostcodeWidget global.

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, runs the whole flow in a shadow root so neither your CSS nor the widget’s can reach the other, and resolves with the PostcodeSelection, or null if the user dismissed it with the close button, Escape, or a press outside the card. The promise rejects when the call itself cannot work: a missing key, an unusable platformBaseUrlOverride or styleUrl, a second widget opened while one is already on screen, a page with no origin (opened as a file:// URL), or a call made where there is no DOM (server-side rendering).

Options

Option	Type	Notes
`key`	`string`	Required. Your publishable key.
`identifierType`	`"nin" \| "email"`	Which identifier your integration uses. Default `"email"`.
`identifier`	`string`	Locks the identity field and shows a confirm screen when set.
`environment`	`'production' \| 'staging'`	Which deployment to talk to. Keys are minted per environment, so a `nipost_pk_test_…` key only resolves on staging. Defaults to production.
`platformBaseUrlOverride`	`string`	Points at a platform outside the standard environments, such as a local stack. Wins over `environment`. HTTPS, or HTTP on `localhost`.
`styleUrl`	`string`	MapLibre style JSON for the map. Defaults to the keyless OpenFreeMap `liberty` style.
`theme`	`PostcodeWidgetTheme`	Brand colours, radii and font stacks, the same tokens as the native SDKs.
`onSelect`	`(s: PostcodeSelection) => void`	Fired before the promise resolves.
`onClose`	`() => void`	Fired when the user dismisses the widget.
`onError`	`(e: {code, message}) => void`	Every failed request behind the screens, with the platform’s own error code.

Origins

The publishable key carries an origin allowlist, and because the widget calls the platform from the browser, the Origin header your page sends is what gets checked. Every origin that opens the widget must be on the key, or the request comes back 403 origin_not_allowed, shown on the identity screen and passed to onError. Add every production, staging and development origin when you create the key.

Theming

await PostcodeWidget.open({
  key: "nipost_pk_live_…",
  theme: {
    ink: "#1A1A2C",
    accent: "#EBC700",
    accentDark: "#D6B500",
    surface: "#FFFFFF",
    surfaceRaised: "#F9FAFB",
    border: "#DFE3E8",
    textPrimary: "#212B36",
    textSecondary: "#637381",
    textTertiary: "#919EAB",
    codeInk: "#17191A",
    codeMuted: "#A7A7A7",
    danger: "#BE123C",
    radius: 12,
    pillRadius: 50,
    sheetRadius: 28,
    fontFamily: "Inter, system-ui, sans-serif",
    codeFontFamily: "'Google Sans Code', ui-monospace, monospace",
  },
});

Every token is optional; anything you leave out keeps the NIPOST default. The two font stacks exist because the package bundles no fonts. Colours take hex (#fff, #EBC700, #EBC700CC) or rgb() / rgba() with numeric channels, radii are pixel numbers clamped to 64, and font stacks may only contain the characters a font stack needs. Values that are none of those are dropped rather than written into a stylesheet.

Find by location

“Get Postcode on Map” opens a MapLibre map that follows the browser’s position, draws its accuracy circle, and reveals the postcode plate segment by segment as the fix tightens: state and LGA above 50 m, district from 50 m, area from 20 m, and the full unit at 8 m or better. Nearby postcodes appear as tappable markers for the cases where the exact building is ambiguous. Geolocation needs a secure context, so serve the embedding page over HTTPS, and note that a Permissions Policy on your page that blocks geolocation blocks it here too. If the map library cannot load, the screen says so and the postcode still resolves without it.

Bundle size

Build	Size	Why
`dist/index.js` (ESM)	~95 KB	`maplibre-gl` stays external, so your bundler code-splits it and loads it when the user opens the map
`dist/sdk.js` (CDN)	~850 KB	a script tag has no bundler, so the map library is inlined

Prefer the npm build when you have a bundler.

Getting started

Concepts

Widget

Usage

Options

Origins

Theming

Find by location

Bundle size

​Usage

​Options

​Origins

​Theming

​Find by location

​Bundle size

Usage

Options

Origins

Theming

Find by location

Bundle size