Integrate GivePay into your Next.js or React application with the React component

Installation

Install the GivePay React package via npm:

npm install givepay-js

Quick Start: Global Configuration

The recommended way to use GivePay in Next.js/React applications is to configure the SDK globally and use the component without props. This approach is cleaner and allows you to manage payment configuration in a central place.

1. Configure the SDK

You can configure the SDK imperatively using the GivePay object. This is typically done in your component or a layout file.

import { GivePay } from 'givepay-js/react';

// Configure SDK globally
GivePay.configure('gp_test_pk_your_key_here');
GivePay.setText('Donate Now'); // Optional: Customize button text
GivePay.setPaymentOptions({
    currency: 'GBP',
    line_items: [
        {
            quantity: 1,
            amount: 200, // £2.00
            country_iso: 'GB',
            intention: 'General Donation',
            project: 'Winter Appeal 2024'
        }
    ],
    payer: {
        email: 'donor@example.com',
        billing_address: {
            country: 'GB',
            city: 'London',
            line1: '123 Main St',
            postcode: 'SW1A 1AA',
            state: 'London'
        },
        first_name: 'John',
        last_name: 'Doe',
        phone: '+447700900123'
    },
    return_url: 'https://yourcharity.org/success'
});

2. Use with Next.js Dynamic Import

To prevent hydration errors in Next.js (since the SDK interacts with the window object), use next/dynamic with ssr: false to import the button component.

'use client';

import dynamic from 'next/dynamic';
import { GivePay } from 'givepay-js/react';

// ... configuration code ...

// Import GivePayButton with SSR disabled
const GivePayButton = dynamic(
    () => import('givepay-js/react'),
    { ssr: false }
);

export default function CheckoutPage() {
    return (
        <div>
            <h1>Checkout</h1>
            {/* Button uses global defaults */}
            <GivePayButton />
        </div>
    );
}

Complete Example

Here is a complete example of a checkout page using the Global Configuration pattern:

'use client';

import dynamic from 'next/dynamic';
import { GivePay } from 'givepay-js/react';

// Configure SDK globally
GivePay.configure('gp_test_pk_your_key_here');
GivePay.setText('Donate Now');
GivePay.setPaymentOptions({
    currency: 'GBP',
    line_items: [
        {
            quantity: 1,
            amount: 200,
            country_iso: 'GB',
            intention: 'General Donation',
            project: 'Gaza Winter Appeal 2024'
        }
    ],
    payer: {
        email: 'test@example.com',
        billing_address: {
            country: 'GB',
            city: 'Anytown',
            line1: '123 Main St',
            postcode: '12345',
            state: 'CA'
        },
        first_name: 'John',
        last_name: 'Doe',
        phone: '123-456-7890'
    },
    return_url: 'https://example.com/success'
});

// Import GivePayButton with SSR disabled to prevent hydration errors
const GivePayButton = dynamic(
    () => import('givepay-js/react'),
    { ssr: false }
);

export default function CheckoutPage() {
    return (
        <div className="min-h-screen bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
            <div className="max-w-md mx-auto bg-white rounded-lg shadow-md p-8">
                <h1 className="text-2xl font-bold text-gray-900 mb-6">
                    Checkout
                </h1>

                <div className="mb-6">
                    <h2 className="text-lg font-semibold text-gray-700 mb-2">
                        Gaza Winter Appeal 2024
                    </h2>
                    <p className="text-gray-600">
                        Amount: £2.00
                    </p>
                </div>

                <div className="border-t border-gray-200 pt-6">
                    {/* Button uses global defaults */}
                    <GivePayButton />
                </div>
            </div>
        </div>
    );
}

API Reference

`GivePay` Object

The GivePay object provides static methods to configure the SDK.

Method	Description
`configure(publicKey: string)`	Initialize the SDK with your public key.
`setPaymentOptions(options: PaymentOptions)`	Set the payment configuration (currency, items, payer, etc.).
`setColour(color: string)`	Set the primary color of the payment button.
`setText(text: string)`	Set the text displayed on the payment button.
`setTextColor(color: string)`	Set the text color of the payment button.
`setLineItems(items: LineItem[])`	Update just the line items.
`setPayer(payer: Payer)`	Update just the payer information.
`setButtonOptions(options: ButtonOptions)`	Set advanced button styling options.

`GivePayButton` Component

The GivePayButton component renders the payment button. When used with global configuration, it requires no props.

However, you can still pass props to override global defaults if needed (Legacy/Local Mode).

Prop	Type	Required	Description
`publicKey`	`string`	No	Overrides the globally configured key.
`paymentOptions`	`PaymentOptions`	No	Overrides global payment options.
`buttonOptions`	`ButtonOptions`	No	Overrides global button options.

Advanced Usage

Hybrid Configuration

You can mix global configuration with local overrides. This is useful if you want to set common defaults (like the public key and styles) globally, but pass specific payment details locally.

// Configure common settings
GivePay.configure('gp_test_pk_your_key_here');

// ... inside component ...
<GivePayButton
  paymentOptions={{
    currency: "GBP",
    line_items: [{ ... }],
    payer: { ... },
    return_url: "..."
  }}
/>

TypeScript Support

The package includes full TypeScript definitions.

import { GivePay } from 'givepay-js/react';
import type { PaymentOptions, LineItem } from 'givepay-js/types';

const options: PaymentOptions = {
  // ...
};

GivePay.setPaymentOptions(options);

Next.js / React Package