React Native

npm install @nipost/postcode-widget-react-native

npm publication is pending — until it lands, consume the package from the repository checkout. Its Android side resolves ng.gov.postcode:postcode-widget from Maven Central, so no local wiring is needed for that half. The package is a thin JavaScript layer over the native Android and iOS SDKs, so the flow, the styling and the wire shape are identical on both platforms. It works in bare React Native and Expo, on both architectures — it ships a codegen TurboModule spec that also resolves through NativeModules on the old architecture, and it registers no native views, which is what keeps it architecture-agnostic. Verified building on RN 0.76.5 for iOS and Android on each. React Native 0.82 removed the old architecture entirely, so that only matters for 0.74–0.81.

Usage

import { showPostcodeWidget } from '@nipost/postcode-widget-react-native';

const selection = await showPostcodeWidget({
  publishableKey: 'nipost_pk_live_…',
  identifierType: 'email',
  prefilledIdentifier: 'ada@example.com',
});

if (selection) {
  console.log('picked', selection.formatted);
}

showPostcodeWidget() opens the widget full-screen in its own native container — identity screen (replaced by a confirm screen when prefilledIdentifier is set), saved postcodes, and the map-based discover flow — and resolves with the PostcodeSelection, or null if the user closed without picking. It rejects when the publishable key is missing or the native module has not been linked into the app binary.

Expo

The package ships custom native code, so it cannot run in Expo Go — use a development build. Add the config plugin to app.json / app.config.js:

{
  "expo": {
    "plugins": ["@nipost/postcode-widget-react-native"]
  }
}

Optionally override the iOS location purpose string:

{
  "expo": {
    "plugins": [
      [
        "@nipost/postcode-widget-react-native",
        { "locationWhenInUsePermission": "We use your location to suggest the postcode you are standing in." }
      ]
    ]
  }
}

Then generate the native projects with npx expo prebuild (or build on EAS) and run npx expo run:ios / npx expo run:android. The plugin sets NSLocationWhenInUseUsageDescription in Info.plist, never overwriting a value you already set, and raises the iOS deployment target only when your project pins something lower than 15.0. It adds no Android permissions: INTERNET and location are declared by the widget SDK’s own manifest and arrive through manifest merging.

Bare React Native

Autolinking picks the module up — no manual registration, and no config plugin is involved:

npx pod-install

Then rebuild the app. Add NSLocationWhenInUseUsageDescription to ios/<App>/Info.plist yourself for the “Get Postcode on Map” discover flow; the widget requests location permission itself at the moment of use.

Configuration

Field	Notes
`publishableKey`	Required. Your `nipost_pk_…` key.
`identifierType`	`'nin'` or `'email'`. Defaults to `'email'`.
`prefilledIdentifier`	Locks the identity field and shows a confirm screen when set.
`environment`	`'production'` (default) or `'staging'`. Keys are minted per environment — a `nipost_pk_test_…` key only resolves on staging.
`platformBaseUrlOverride`	A host outside the standard environments (local stack, preview deploy). Wins over `environment`.
`styleUrl`	Override the map style for the discover flow.

The package requires React Native 0.74+, iOS 15+ and Android minSdk 24. The native SDKs bring their own UI, so no host-side screens, navigation or permissions setup is needed.

Getting started

Concepts

Widget

Usage

Expo

Bare React Native

Configuration

​Usage

​Expo

​Bare React Native

​Configuration

Usage

Expo

Bare React Native

Configuration