React Native Integration

The @geophrase/react-native package provides the <GeophraseConnect /> component for integrating the Geophrase address selector into any React Native app.

Expo Notice: This SDK uses native modules and does not work in Expo Go. You must use EAS Build or a custom dev client.

Prerequisites

Create a Geophrase Account.
Generate an API Key from the Dashboard. Every integration needs its Key ID (the public prefix, shown in the dashboard); client mode also needs the secret key.

1. Install

npm install @geophrase/react-native react-native-webview react-native-device-info @react-native-community/geolocation

iOS

npx pod-install

Add to ios/AppName/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to accurately place the pin on your address.</string>

Android

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

2. Implementation

The snippet below uses mode="server", so the only credential you need in the app is your public Key ID. No secret API key is required. Swap in your own apiKeyId and drop it into your app to see the widget.

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { GeophraseConnect } from '@geophrase/react-native';

export default function Checkout() {
    const [visible, setVisible] = useState(false);
    const [result, setResult] = useState(null);

    return (
        <View>
            <Button title="Select Delivery Location" onPress={() => setVisible(true)} />

            <GeophraseConnect
                visible={visible}

                apiKeyId="YOUR_API_KEY_ID"  // required in both modes; your public Key ID

                // 'server' (used here): widget returns a requestId. Pass it to your backend to resolve the address. No secret key needed.
                // 'client' (default):   widget resolves and returns the full address directly. Requires 'apiKey'.
                mode="server"

                // apiKey="YOUR_API_KEY"    // secret key, required when mode="client"
                theme="system"              // 'light' | 'dark' | 'system'
                orderId="ORD-98765"         // your internal reference ID
                phone="9999999999"          // prefills the phone field

                onSuccess={(result) => {
                    // server mode → { requestId: "..." }. POST to your backend.
                    // client mode → full address object.
                    setResult(result);
                    setVisible(false);
                }}
                onError={(error) => console.error('Geophrase error:', error.message)}
                onClose={() => setVisible(false)}
            />
        </View>
    );
}

View full example on GitHub

3. TypeScript Support

The package ships with native TypeScript definitions. Import GeophraseAddress and GeophraseRequestId to type the onSuccess result.

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { GeophraseConnect, GeophraseAddress, GeophraseRequestId } from '@geophrase/react-native';

export default function Checkout() {
    const [visible, setVisible] = useState(false);
    const [result, setResult] = useState<GeophraseAddress | GeophraseRequestId | null>(null);

    return (
        <View>
            <Button title="Select Delivery Location" onPress={() => setVisible(true)} />

            <GeophraseConnect
                visible={visible}
                apiKeyId="YOUR_API_KEY_ID"
                mode="server"
                onSuccess={(data) => { setResult(data); setVisible(false); }}
                onError={(error) => console.error('Geophrase error:', error.message)}
                onClose={() => setVisible(false)}
            />
        </View>
    );
}

Configuration Props

Prop	Type	Default	Required	Description
`visible`	`boolean`	-	Yes	Controls the visibility of the widget modal.
`apiKeyId`	`string`	-	Yes	Your 8-character public Key ID (shown in the dashboard). Required in both modes; identifies your account to the widget.
`mode`	`string`	`'client'`	No	`'client'` resolves the address in the app. `'server'` returns a `requestId` for your backend to exchange.
`apiKey`	`string`	-	Conditional	Your secret Geophrase API key (the full key string). Required when `mode="client"`.
`theme`	`string`	`'system'`	No	`'light'`, `'dark'`, or `'system'` (follows OS preference).
`orderId`	`string`	-	No	Your internal reference ID. In client mode it is forwarded to the Resolve endpoint; in server mode you forward it yourself.
`noteForAgent`	`string`	-	No	Note shown to your delivery agent, never to the customer. Client mode only; notes over 300 characters are cut. It is sent from the customer's device, so the customer can change it; send payment instructions, such as cash to collect, from your server or the dashboard. In server mode, send `note_for_agent` with your resolve call.
`phone`	`string`	-	No	Pre-fills the phone field with a 10-digit Indian mobile number.
`onSuccess`	`function`	-	Yes	Receives an `Address` object in client mode, or `{ requestId }` in server mode.
`onError`	`function`	-	No	Receives `{ type, status?, message }` on API or network errors.
`onClose`	`function`	-	No	Called when the user dismisses the widget without selecting an address.

Next step

Flutter