React Hooks

The React SDK provides two hooks for accessing PPP data and computing localized prices.

usePPP

The primary hook for accessing all PPP data. Returns the full context value from the nearest GoPayLocalProvider.

import { usePPP } from '@gopaylocal/react';

function PricingBanner() {
  const {
    discount,
    country,
    flag,
    code,
    currencyCode,
    currencySymbol,
    fxRate,
    localPrice,
    formatPrice,
    isLoading,
    error,
    data,
  } = usePPP();

  if (isLoading) return <div>Loading...</div>;
  if (error) return null; // Fail silently

  if (discount > 0) {
    return (
      <div>
        {flag} {discount}% off for {data?.countryName}!
        <br />
        Use code <strong>{code}</strong> at checkout.
        <br />
        Pro plan: <span>{formatPrice(localPrice(9.99))}</span>/mo
      </div>
    );
  }

  return null;
}

Return Value

Property	Type	Description
data	PPPResponse | null	Raw API response, or null if not loaded
isLoading	boolean	Whether the API request is in-flight
error	Error | null	Error from the API request
country	string | null	ISO country code (e.g., 'IN')
discount	number	Discount percentage (0-100)
code	string | null	Coupon code
currencyCode	string	Local currency code (e.g., 'INR')
currencySymbol	string	Local currency symbol (e.g., '₹')
fxRate	number	FX rate from base currency to local currency
localPrice	(basePrice: number) => number	Convert base price to local discounted price
formatPrice	(price: number, options?: Intl.NumberFormatOptions) => string	Format a number as local currency
flag	string	Country flag emoji

Helper Functions

localPrice(basePrice) — Applies both the PPP discount and FX conversion:

const { localPrice } = usePPP();

// $99.99 with 30% discount and INR conversion (fxRate ~83)
localPrice(99.99); // → 5,819.27 (= 99.99 × 0.70 × 83)

formatPrice(amount, options?) — Formats a number using Intl.NumberFormat with the visitor’s currency:

const { formatPrice } = usePPP();

formatPrice(5819.27); // → "₹5,819.27"
formatPrice(5819.27, { maximumFractionDigits: 0 }); // → "₹5,819"

Error Handling

usePPP() throws if called outside a GoPayLocalProvider:

Error: usePPP() must be used inside a <GoPayLocalProvider>.
Wrap your component tree with <GoPayLocalProvider apiKey="...">.

Tip

Wrap only the part of your app that needs PPP data. You don’t have to wrap the entire app if only your pricing page uses PPP.

---

usePrice

A convenience hook that computes a fully formatted localized price from a base price. Built on top of usePPP().

import { usePrice } from '@gopaylocal/react';

function PriceDisplay() {
  const {
    formatted,
    formattedOriginal,
    hasDiscount,
    discount,
    integer,
    decimal,
    currencySymbol,
    currencyCode,
  } = usePrice({ price: 99.99 });

  return (
    <div>
      {hasDiscount && (
        <>
          <s>{formattedOriginal}</s>
          <span> {discount}% off</span>
        </>
      )}
      <strong>{formatted}</strong>
    </div>
  );
}

Options

Option	Type	Default	Description
price	number	(required)	Base price in your default currency
localize	boolean	true	Whether to convert to visitor’s local currency
showDecimal	boolean	true	Whether to show decimal digits
minimumDecimalDigits	number	—	Minimum decimal digits for formatting
maximumDecimalDigits	number	—	Maximum decimal digits for formatting

Return Value

Property	Type	Description
originalPrice	number	The base price (unchanged)
discountedPrice	number	Price after PPP discount (in base currency)
localPrice	number	Localized price (discounted + FX-converted)
formatted	string	Formatted local price (e.g., "₹4,999")
formattedOriginal	string	Formatted original price (e.g., "$99.99")
discount	number	Discount percentage (0-100)
integer	string	Integer part of formatted price (e.g., "4,999")
decimal	string	Decimal part (e.g., "99"). Empty for zero-decimal currencies
currencySymbol	string	Currency symbol (e.g., "₹")
currencyCode	string	Currency code (e.g., "INR")
hasDiscount	boolean	Whether a discount is active

Examples

Simple price display:

const { formatted } = usePrice({ price: 49.99 });
// → "₹3,499" (India, 30% off, INR conversion)
// → "$49.99" (US, no discount)

Strikethrough pricing:

function StrikethroughPrice({ price }: { price: number }) {
  const { formatted, formattedOriginal, hasDiscount } = usePrice({ price });

  return (
    <span>
      {hasDiscount && <s style={{ opacity: 0.5 }}>{formattedOriginal}</s>}{' '}
      <strong>{formatted}</strong>
    </span>
  );
}

Custom price layout with separate integer/decimal:

function FancyPrice({ price }: { price: number }) {
  const { integer, decimal, currencySymbol } = usePrice({ price });

  return (
    <span style={{ fontSize: '2rem' }}>
      <span style={{ fontSize: '1rem' }}>{currencySymbol}</span>
      {integer}
      {decimal && <sup style={{ fontSize: '0.8rem' }}>.{decimal}</sup>}
    </span>
  );
}

Without currency conversion (discount only):

const { formatted } = usePrice({ price: 99.99, localize: false });
// → "$69.99" (30% off, stays in USD)

No decimals:

const { formatted } = usePrice({ price: 99.99, showDecimal: false });
// → "₹5,000" (rounded to nearest integer)