React Integration

The @geophrase/react package provides a native useGeophrase hook for integrating the Connect Widget into any React application.

Prerequisites

Create a Geophrase Account.
Generate an API Key from the Dashboard.

1. Install the Package

npm install @geophrase/react

2. Basic Implementation

The useGeophrase hook manages the widget lifecycle and returns an open function you attach to any button or event handler.

import { useState } from 'react';
import { useGeophrase } from '@geophrase/react';

function Checkout() {
  const [result, setResult] = useState(null);

  const { open } = useGeophrase({
    keyId: 'YOUR_API_KEY_ID',  // required in every mode; your public Key ID

    // --- MODE ---
    // 'server' (used here): widget returns a short-lived requestId. Pass it to your backend to resolve the address. No secret key in the frontend.
    // 'client' (default):   widget resolves and returns the full address directly. Requires 'key'.
    mode: 'server',

    // key: 'YOUR_API_KEY', // secret key, required when mode is 'client'

    // --- OPTIONAL ---
    theme: 'system',        // 'light' | 'dark' | 'system'
    orderId: 'ORD-98765',   // your internal reference ID
    phone: '9999999999',    // prefills the phone field

    // --- CALLBACKS ---
    onSuccess: (result) => {
      // server mode → result is { requestId: "..." }. POST this to your backend.
      // client mode → result is the full address object.
      setResult(result);
    },
    onError:  (error) => console.error('Geophrase error:', error.message),
    onClose:  () => console.log('User closed the widget.')
  });

  return (
    <div>
      <button onClick={open}>Select Delivery Location</button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}

export default Checkout;

View full React example on GitHub

3. TypeScript Support

The @geophrase/react and @geophrase/core packages ship with native TypeScript definitions. Import GeophraseAddress and GeophraseRequestId from @geophrase/core to type the onSuccess result.

import { useState } from 'react';
import { useGeophrase } from '@geophrase/react';
import type { GeophraseAddress, GeophraseRequestId } from '@geophrase/core';

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

  const { open } = useGeophrase({
    keyId: 'YOUR_API_KEY_ID',
    mode: 'server',
    onSuccess: (data) => setResult(data),
    onError:   (error) => console.error('Geophrase error:', error.message)
  });

  return (
    <div>
      <button onClick={open}>Select Delivery Location</button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}

Configuration Options

Parameter	Type	Default	Required	Description
`keyId`	`string`	-	Yes	Your Key ID, the public prefix of your API key shown in the dashboard. Required in both modes; it tells the widget which account the request belongs to.
`mode`	`string`	`'client'`	No	`'client'` resolves the address in the browser and returns the full address object. `'server'` returns a short-lived `requestId` for your backend to exchange. See Client vs. Server Mode.
`key`	`string`	-	Conditional	Your secret Geophrase API key (the full key string). Required when `mode` is `'client'`. Omit in server mode.
`theme`	`string`	`'system'`	No	Widget theme. `'light'`, `'dark'`, or `'system'` (follows the OS preference).
`orderId`	`string`	-	No	Your internal reference ID. In client mode it is forwarded to the Resolve endpoint and stored against the captured address; in server mode you forward it yourself. Echoed back in the dashboard.
`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	The customer's 10-digit phone number. Pre-fills the phone field in the widget.
`onSuccess`	`function`	-	Yes	Called on completion. Receives an Address Object in client mode, or `{ requestId }` in server mode.
`onError`	`function`	-	No	Called on API or network errors. Receives `{ type, status?, message }`.
`onClose`	`function`	-	No	Called when the user closes the widget without selecting an address.

Next step

Next.js