DonateProvider | ArcBlock

The DonateProvider is a crucial context provider that manages the state and settings for all donation-related components within your application. It handles fetching configuration from the backend, caching it for performance, and providing it to components like CheckoutDonate.

To use any donation features, you must wrap your components with DonateProvider. This provider must also be nested within a PaymentProvider to ensure access to the necessary payment context and session information.

How It Works

The DonateProvider performs several key functions:

Fetches Settings
On mount, it calls an API endpoint to retrieve the donation settings associated with the unique mountLocation prop. These settings determine the behavior of child donation components.
Caches Data
To improve performance and reduce network requests, the fetched settings are stored in localStorage. The cache is automatically used on subsequent loads and can be manually cleared if needed.
Provides Context
It uses React's Context API to pass down the settings and control functions (refresh, updateSettings) to any descendant component that needs them.
Enables Donations
For administrative users ('owner' or 'admin'), if the donation instance is inactive but the enableDonate prop is set, the provider will render a UI to activate it.

Props

The DonateProvider accepts the following props to configure its behavior:

Prop	Type	Required	Description
`mountLocation`	`string`	Yes	A unique string identifier for this specific donation instance. This is used as the key for fetching, caching, and updating settings.
`description`	`string`	Yes	A human-readable description to help identify this donation instance in the system backend or logs.
`children`	`ReactNode`	Yes	The child components that will render inside the provider, typically including `CheckoutDonate`.
`defaultSettings`	`DonateConfigSettings`	No	An object with default settings to apply if no settings are found on the backend. See the type definition below for available options.
`active`	`boolean`	No	Sets the initial active state for the donation instance when it's first created. Defaults to `true`.
`enableDonate`	`boolean`	No	If `true`, allows admin users to enable this donation instance from the UI if it's currently inactive. Defaults to `false`.

DonateConfigSettings Type

This is the shape of the defaultSettings object:

DonateConfigSettings type

export interface DonateConfigSettings {
  amount?: {
    presets?: string[]; // e.g., ['1', '5', '10']
    preset?: string; // Default selected preset amount
    custom: boolean; // Allow users to enter a custom amount
    minimum?: string; // Minimum custom amount
    maximum?: string; // Maximum custom amount
  };
  btnText?: string; // Text for the main donation button, e.g., "Donate"
  historyType?: 'table' | 'avatar'; // How to display the list of supporters
}

Usage Example

Here is a complete example of setting up a donation section on a page. It shows how to wrap CheckoutDonate with both DonateProvider and PaymentProvider.

App.tsx

import {
  PaymentProvider,
  DonateProvider,
  CheckoutDonate,
} from '@blocklet/payment-react';
import { useSessionContext } from './hooks/use-session'; // Your custom session hook

function DonationSection() {
  const { session, connectApi } = useSessionContext();

  // Render nothing or a login prompt if the user is not authenticated
  if (!session?.user) {
    return <div>Please log in to make a donation.</div>;
  }

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <DonateProvider
        mountLocation="support-our-blog-post-123"
        description="Donation for the article 'Getting Started with React'"
        defaultSettings={{
          btnText: 'Support the Author',
          amount: {
            presets: ['1', '5', '10'],
            custom: true,
            minimum: '1',
          },
        }}>
        <CheckoutDonate
          settings={{
            target: 'post-123', // A unique identifier for the donation target
            title: 'Support the Author',
            description: 'If you found this article helpful, feel free to buy me a coffee.',
            reference: 'https://your-site.com/posts/123',
            beneficiaries: [
              {
                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
                share: '100',
              },
            ],
          }}
        />
      </DonateProvider>
    </PaymentProvider>
  );
}

Hooks and Utilities

The library also exports several helper functions for advanced control over the donation context and cache.

useDonateContext

A React hook to access the donation context directly from any child component of DonateProvider.

import { useDonateContext } from '@blocklet/payment-react';

function CustomDonationInfo() {
  const { settings, refresh } = useDonateContext();

  return (
    <div>
      <p>Donations are currently {settings.active ? 'enabled' : 'disabled'}.</p>
      <button onClick={() => refresh(true)}>Refresh Settings</button>
    </div>
  );
}

clearDonateCache

This function manually removes the cached settings for a specific mountLocation from localStorage. This is useful when you know the settings have changed on the server and you want to force a fresh fetch on the next component render.

import { clearDonateCache } from '@blocklet/payment-react';

// Call this function when you need to invalidate the cache
clearDonateCache('support-our-blog-post-123');

clearDonateSettings

This function sends a DELETE request to the backend API to permanently remove the settings for a given mountLocation. It also clears the local cache for that location.

import { clearDonateSettings } from '@blocklet/payment-react';

async function deleteDonationInstance() {
  try {
    await clearDonateSettings('support-our-blog-post-123');
    console.log('Donation settings have been deleted.');
  } catch (error) {
    console.error('Failed to delete settings:', error);
  }
}

With DonateProvider configured, you can now implement various donation features. The next step is to explore the main component for displaying the donation UI.

➡️ Next, learn how to use the CheckoutDonate component to render the donation widget.