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

# Flutter

> Embed the postcode widget in a Flutter app with nipost_postcode_widget.

```yaml theme={null}
dependencies:
  nipost_postcode_widget: ^0.1.0
```

## Usage

```dart theme={null}
import 'package:nipost_postcode_widget/nipost_postcode_widget.dart';

final selection = await PostcodeWidget.show(
  context,
  PostcodeWidgetConfig(
    publishableKey: 'nipost_pk_live_…',
    identifierType: IdentifierType.email,
    prefilledIdentifier: 'ada@example.com',
  ),
);

if (selection != null) {
  debugPrint('picked ${selection.formatted}');
}
```

`show()` opens the widget as a full-screen modal flow — identity screen (skipped
when `prefilledIdentifier` is set), bookmarks, and search — and returns the
[`PostcodeSelection`](/widget/overview#the-selection-payload), or `null` if the
user backed out. `selection.toJson()` produces exactly the wire shape every
other SDK delivers.

## Configuration

| Field                                | Notes                                             |
| ------------------------------------ | ------------------------------------------------- |
| `publishableKey`                     | **Required.** Your `nipost_pk_…` key.             |
| `identifierType`                     | `IdentifierType.nin` or `IdentifierType.email`.   |
| `prefilledIdentifier`                | Skips the identity screen when set.               |
| `platformBaseUrl` / `gatewayBaseUrl` | Override hosts (staging / local dev).             |
| `theme`                              | `PostcodeWidgetTheme` overrides for brand colors. |

The package depends only on Flutter and `dio`, holds no global state, and can
be instantiated from multiple places in the same app.