@blocklet/payment-react/docs/overview.md

Reusable react components for payment kit v2

# Overview

`@blocklet/payment-react` is a comprehensive React component library designed to streamline the integration of payment flows, subscriptions, and donation systems into your blocklets. Built on top of [Payment Kit](https://www.arcblock.io/docs/arcblock-payment-kit), it provides a suite of pre-built, customizable, and production-ready components to help you build powerful payment experiences with minimal effort.

## Key Features

<x-cards data-columns="3">
  <x-card data-title="Pre-built UI Components" data-icon="lucide:layout-template">
    Includes a rich set of components like checkout forms, pricing tables, and donation widgets to cover common payment scenarios out of the box.
  </x-card>
  <x-card data-title="Customizable Themes" data-icon="lucide:palette">
    Gain full control over the look and feel of your payment flows using Material-UI themes, ensuring a consistent user experience.
  </x-card>
  <x-card data-title="i18n Support" data-icon="lucide:languages">
    Built-in internationalization support allows you to easily localize component text for a global audience.
  </x-card>
  <x-card data-title="Comprehensive Payment Operations" data-icon="lucide:credit-card">
    Easily handle complex payment logic, including subscriptions, refunds, invoice management, and metered billing.
  </x-card>
  <x-card data-title="Optimized Performance" data-icon="lucide:package-minus">
    Optimize your application's bundle size and improve performance with built-in support for lazy loading and dynamic component imports.
  </x-card>
</x-cards>

## How It Works

The library is architected around a provider-component model. The `PaymentProvider` is the core of the library, creating a context that manages authentication, API communication, and state. All other payment components must be wrapped within this provider to function correctly. This centralizes the payment logic and makes individual components lightweight and focused.

```d2 High-Level Architecture
direction: down

User: {
  shape: c4-person
}

Your-Application: {
  label: "Your Application"
  shape: rectangle

  PaymentProvider: {
    label: "PaymentProvider"
    shape: rectangle

    Payment-Components: {
      label: "Payment Components"
      shape: rectangle
      grid-columns: 2

      CheckoutForm: { label: "CheckoutForm" }
      CheckoutTable: { label: "CheckoutTable" }
      CheckoutDonate: { label: "CheckoutDonate" }
      CustomerInvoiceList: { label: "CustomerInvoiceList" }
    }
  }
}

Payment-Kit-Backend: {
  label: "Payment Kit Backend"
  shape: cylinder
}

User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"

```

## What You Can Build

- **Subscription Services:** Quickly implement pricing pages and checkout flows for SaaS products using `CheckoutTable`.
- **E-commerce Checkouts:** Build one-time payment forms for selling goods with `CheckoutForm`.
- **Donation Systems:** Add flexible donation widgets to support creators or causes with `CheckoutDonate`.
- **Customer Portals:** Display invoice history and manage payment methods for users with `CustomerInvoiceList` and other history components.

## Next Steps

Now that you have an overview of what `@blocklet/payment-react` offers, the best way to learn is by building something.

Dive into our [Getting Started](./getting-started.md) guide to install the library and create your first payment form in minutes.