> ## 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.

# React Native

> Embed the postcode widget in a React Native or Expo app with @nipost/postcode-widget-react-native.

```bash theme={null}
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

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

```json theme={null}
{
  "expo": {
    "plugins": ["@nipost/postcode-widget-react-native"]
  }
}
```

Optionally override the iOS location purpose string:

```json theme={null}
{
  "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:

```bash theme={null}
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.