# CheckoutForm
The `CheckoutForm` component is the primary entry point for handling payment links and checkout sessions. It serves as a high-level wrapper that automatically fetches the necessary data based on a provided ID and renders the appropriate payment or donation interface. This component provides the most straightforward method for integrating a complete checkout flow into your application.
For the `CheckoutForm` to function correctly, it must be nested within a `PaymentProvider`. This provider supplies the necessary context, such as session information and API configuration. For detailed setup instructions, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
## How It Works
The component manages the entire checkout process through a clear, sequential flow:
1. **Initialization**: The component is mounted with an `id` prop, which must be either a `paymentLink` ID (prefixed with `plink_`) or a `checkoutSession` ID (prefixed with `cs_`).
2. **Data Fetching**: It sends a request to the payment backend to retrieve the complete checkout context, which includes available payment methods, line items, and customer details.
3. **UI Rendering**: Based on the `formType` prop, it internally renders either the standard `Payment` component for purchases or the specialized `DonationForm` for contributions.
4. **State Management**: It handles the full lifecycle of the transaction, managing loading states, completion status, and any potential errors.
## Props
The `CheckoutForm` component is configured using the following properties.
The unique identifier for the payment link (`plink_...`) or checkout session (`cs_...`).
Defines the rendering mode. `'standalone'` creates a full-page view, while `'inline'` embeds the form within an existing container. The `-minimal` variants hide the order summary.
Specifies the type of form to render. Use `'donation'` to activate the specialized donation user interface.
A callback function that is executed upon successful payment completion. It receives the final checkout context as an argument.
A callback function that is executed if an error occurs during the checkout process.
A callback function that fires whenever a value in the payment form changes.
If provided, a back button is rendered. This function is called when the button is clicked.
An object containing extra parameters to be appended to the URL when initiating a checkout session from a payment link.
Controls the component's theme. `'inherit'` uses the parent theme, while `'default'` applies the library's standard theme. A custom theme object can also be provided.
A string identifier used for customizing UI elements, such as button text, or for tracking specific analytics events.
## Usage Examples
### Basic Inline Payment Form
This is the most common use case, where the payment form is embedded directly into a page of your application. The component handles all data fetching and state management internally.
```javascript MyStorePage.jsx icon=logos:react
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context'; // This is an example hook from your application
export default function MyStorePage() {
const { session, connectApi } = useSessionContext();
const handlePaymentSuccess = (result) => {
console.log('Payment successful!', result);
alert('Thank you for your purchase!');
};
const handlePaymentError = (error) => {
console.error('Payment failed:', error);
alert('Sorry, your payment could not be processed.');
};
return (
Checkout
);
}
```
### Standalone Full-Page Checkout
Use `mode="standalone"` to render a dedicated, full-page checkout experience. This mode is ideal for redirecting the user to a separate URL to complete their payment without distractions.
```javascript CheckoutPage.jsx icon=logos:react
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';
export default function CheckoutPage() {
const { session, connectApi } = useSessionContext();
// In a real application, you would get this ID from the URL parameters
const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
return (
{
// Redirect to a success page
window.location.href = '/payment-success';
}}
/>
);
}
```
### Donation Form
By setting `formType="donation"`, the component renders a specialized UI tailored for donation campaigns. This form includes features such as amount presets and can display information about the benefits of donating.
```javascript DonationPage.jsx icon=lucide:gift
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';
export default function DonationPage() {
const { session, connectApi } = useSessionContext();
return (
Support Our Cause
alert('Thank you for your generous donation!')}
/>
);
}
```