@ipgeotrace/react

React bindings for IPGeoTrace. Resolve the visitor's location once and share it across your whole component tree with a hook. Built on @ipgeotrace/browser — it uses a publishable key, so it's safe in the client.

Sign up and grab your publishable key at ipgeotrace.com.

Install

npm add @ipgeotrace/react react

Usage

Wrap your app once. The provider calls me() a single time and shares the result — no component refetches on its own.

import { IpGeoTraceProvider } from '@ipgeotrace/react';

export function App() {
  return (
    <IpGeoTraceProvider publishableKey="pk_live_...">
      <Checkout />
    </IpGeoTraceProvider>
  );
}

Then read it anywhere with useVisitorGeo():

import { useVisitorGeo } from '@ipgeotrace/react';

function Checkout() {
  const { data, loading, error } = useVisitorGeo();

  if (loading) return <p>Locating…</p>;
  if (error) return <p>Couldn't detect your location.</p>;

  const currency = data?.country?.currency ?? 'USD';
  return <p>Prices in {currency}</p>;
}

What the hook gives you

• data — the GeoResponse, or undefined until it resolves.
• error — a GeoError if the lookup failed (rate_limited, network_error, …).
• loading — true while the request is in flight.
• refresh() — run me() again. Useful after you know the network changed (e.g. the user toggled a VPN), since the result is never cached — every call reflects the visitor's location right now.

Options

Pass browser-client options, defer the first call, or bring your own client:

// defer the initial lookup until you call refresh()
<IpGeoTraceProvider publishableKey="pk_live_..." immediate={false}>…</IpGeoTraceProvider>

// pass through browser-client options
<IpGeoTraceProvider publishableKey="pk_live_..." options={{ timeoutMs: 3_000 }}>…</IpGeoTraceProvider>

// or share a pre-built client
import { createBrowserClient } from '@ipgeotrace/browser';
const client = createBrowserClient({ publishableKey: 'pk_live_...' });
<IpGeoTraceProvider client={client}>…</IpGeoTraceProvider>

Next.js

This package is marked "use client" and works directly in Next.js client components — there's no separate Next.js frontend package. Keep the provider in a client component (e.g. your root layout's client shell).

See the @ipgeotrace/browser README for the underlying me() client and publishable keys.