CheckoutDonate
The CheckoutDonate component provides a flexible way to implement donation functionality in your application. It supports several display modes, from a simple pre-built button to a fully custom UI, and handles the entire donation flow, including displaying supporter history.
To function correctly, CheckoutDonate must be wrapped within both a PaymentProvider and a DonateProvider. For more details, refer to the PaymentProvider and DonateProvider documentation.
Props#
Prop | Type | Description |
|---|---|---|
|
| Required. An object containing the configuration for the donation instance, such as target, title, and beneficiaries. |
|
| Optional. A callback function that is executed after a donation is successfully paid. |
|
| Optional. A callback function that is executed if an error occurs during the payment process. |
|
| Optional. Toggles between live and test payment modes. If not set, it inherits the value from |
|
| Optional. The time in milliseconds to wait before closing the checkout dialog after a successful payment. Defaults to |
|
| Optional. Determines the rendering mode of the component. Defaults to |
|
| Optional. Customization options for the button when |
|
| Optional. Controls the component's theme. See the Theming guide for more details. Defaults to |
|
| Optional. A render prop function used when |
CheckoutDonateSettings#
This object configures the donation's behavior and appearance.
Property | Type | Description |
|---|---|---|
|
| Required. A unique identifier for the donation instance (e.g., a post ID like |
|
| Required. The title displayed in the donation modal. |
|
| Required. A description shown in the donation modal. |
|
| Required. A reference link for the donation, such as the URL of the page where the donation is being made. |
|
| Required. An array of objects defining who receives the donation and their respective shares. |
|
| Optional. Configures donation amounts, including presets, min/max values, and whether custom amounts are allowed. |
|
| Optional. Customizes the look and feel of the donation button and supporter history display ( |
Basic Usage#
Here is a basic example of how to set up CheckoutDonate. This will render a default donation button and a list of supporters.
import {
PaymentProvider,
DonateProvider,
CheckoutDonate
} from '@blocklet/payment-react';
function DonationSection() {
// Assume session and connectApi are provided by your application's auth context
const session = getSession();
const connectApi = getConnectApi();
return (
<PaymentProvider session={session} connect={connectApi}>
<DonateProvider
mountLocation="unique-page-identifier"
description="Donations for this page"
>
<CheckoutDonate
settings={{
target: "post-123", // Unique ID for this donation target
title: "Support the Author",
description: "If you find this article helpful, feel free to buy me a coffee.",
reference: "https://your-site.com/posts/123",
beneficiaries: [
{
address: "did:abt:z123...", // Beneficiary's DID address
share: "100",
},
],
}}
onPaid={(session) => console.log('Donation successful:', session.id)}
/>
</DonateProvider>
</PaymentProvider>
);
}Usage Modes#
The CheckoutDonate component can be rendered in three different modes, controlled by the mode prop.
Default Mode#
When mode is 'default' (or omitted), the component renders a donation button. Below the button, it displays a history of supporters, which can be configured to show as avatars or a table via settings.appearance.history.variant.
<CheckoutDonate
settings={{
// ... other settings
appearance: {
button: {
text: 'Buy me a coffee ☕',
variant: 'contained',
},
history: {
variant: 'avatar', // or 'table'
},
},
}}
/>Inline Mode#
Setting mode="inline" renders a button that, when clicked, opens a popover containing the donation button and a summary of supporters. This is useful for more compact UIs.
<CheckoutDonate
mode="inline"
settings={{
// ...settings
}}
inlineOptions={{
button: {
text: 'Tip',
variant: 'outlined',
}
}}
/>Custom Mode#
For complete control over the UI, use mode="custom". This mode uses a render prop passed as the children of the component. The function provides you with the state and actions needed to build your own interface.
The children function receives the following arguments:
Argument | Type | Description |
|---|---|---|
|
| A function to call to open the donation payment modal. |
|
| A formatted string representing the total amount donated (e.g., |
|
| An object containing supporter data, including the list of supporters, currency, and payment method details. |
|
| A boolean indicating if the supporter data is currently being fetched. |
|
| The processed donation settings object, including defaults. |
Here is an example of a custom donation UI:
import { CheckoutDonate } from '@blocklet/payment-react';
import { Button, CircularProgress } from '@mui/material';
// ... inside your component, wrapped in Providers
<CheckoutDonate
mode="custom"
settings={{
target: "post-123",
title: "Support the Author",
description: "Your support is appreciated!",
reference: "https://your-site.com/posts/123",
beneficiaries: [{ address: "did:abt:z123...", share: "100" }],
}}
>
{(openDonate, totalAmount, supporters, loading) => (
<div>
<h2>Our Supporters</h2>
<Button variant="contained" onClick={openDonate}>Support Us</Button>
{loading ? (
<CircularProgress />
) : (
<div>
<p>Total Donations: {totalAmount}</p>
<ul>
{supporters.supporters && supporters.supporters.map(supporter => (
<li key={supporter.id}>
<span>{supporter.customer?.name}</span>
<span>
{supporter.amount_total} {supporters.currency?.symbol}
</span>
</li>
))}
</ul>
</div>
)}
</div>
)}
</CheckoutDonate>This custom setup gives you full control over the presentation of donation information.