> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Core components

Shared types, formatters, and the Paddle.js client helpers that every Paddle UI component depends on. These come bundled with other components, so you don't need to install them directly.

---

## About the core components

Most Paddle UI components depend on two shared libraries:

- `paddle-helpers`: includes types, formatters, and payment-method icons.
- `paddle-client`: a singleton Paddle.js instance, event dispatcher, and SDK hooks.

You don't usually install these directly. When you `add` any visual component that needs them, the shadcn CLI pulls them in automatically.

## Paddle helpers

Shared display types, format utilities, and payment method display for Paddle UI components. No SDK dependency — safe to install without @paddle/paddle-js.

**Registry:** [`https://developer.paddle.com/r/paddle-helpers.json`](https://developer.paddle.com/r/paddle-helpers.json)

### Install

```bash
npx shadcn@latest add @paddle/paddle-helpers
```

Also runnable with `pnpm dlx shadcn@latest add @paddle/paddle-helpers` or `yarn dlx shadcn@latest add @paddle/paddle-helpers`.

### Props

- **formatBillingCycle** ((interval: BillingInterval, frequency: number, locale?: string) => string): Localised billing-cycle label, e.g. monthly, every 3 months. Used internally by the pricing and subscription components.
- **formatTrialPeriod** ((trialPeriod: TimePeriodLike) => string): Human-readable trial period (e.g. 7 days, 1 month) from Paddle's trial structure.
- **formatMoney** ((amount: number, currencyCode: string, locale?: string) => string): Localised currency formatting using Intl.NumberFormat. Handles zero-decimal currencies (JPY, KRW, etc.) correctly.
- **parseAmount** ((raw: string, currencyCode: string) => number): Inverse of formatMoney. Converts Paddle's string-amount format to a JavaScript number, handling zero-decimal currencies.
- **formatDate** ((isoString: string, locale?: string) => string): Localised date formatting (e.g. 1 Feb 2025) for any ISO 8601 date string.
- **formatProrationMode** ((mode: string) => string): Human-readable label for a proration billing mode (e.g. prorated_immediately → Prorated, charged today).
- **getPaymentMethodDisplay** ((method: PaymentMethodData) => { label: string; sublabel?: string }): Display strings for a payment method — handles card brand resolution, last-four formatting, and wallet-method labels (Apple Pay, PayPal, etc.).
- **getPaymentMethodIcon** ((method: PaddlePaymentMethodType) => React.ReactNode): SVG icon for a payment method type — covers cards, wallets, and bank methods. Returns a generic card icon as a fallback.

---

## Paddle client utilities

Paddle.js initialization singleton, SDK type re-exports, checkout event mapper, and SDK-layer hooks used by all client-side Paddle blocks.

**Registry:** [`https://developer.paddle.com/r/paddle-client.json`](https://developer.paddle.com/r/paddle-client.json)

### Install

```bash
npx shadcn@latest add @paddle/paddle-client
```

Also runnable with `pnpm dlx shadcn@latest add @paddle/paddle-client` or `yarn dlx shadcn@latest add @paddle/paddle-client`.

### Props

- **getOrCreatePaddle** ((token: string, environment: Environments) => Promise<Paddle | undefined>): Returns a shared Paddle instance, initialising once per token. Subsequent calls with the same token return the cached promise. Also wires up a dispatcher so multiple hooks can subscribe to eventCallback.
- **addPaddleEventListener** ((listener: (event: PaddleEventData) => void) => () => void): Subscribe to Paddle.js checkout events through the shared dispatcher. Returns an unsubscribe function.
- **usePaddlePrices** ((args: UsePaddlePricesArgs) => { prices: Record<string, PriceData>; loading: boolean; error?: Error }): React hook that fetches localised prices for a list of priceIds. Re-fetches when the IDs or country code change. Returns prices keyed by ID.
- **useCheckout** ((args: UseCheckoutArgs) => { open: (options: OpenCheckoutOptions) => void; close: () => void; ready: boolean }): React hook to open and control a Paddle checkout overlay imperatively. Returns open / close functions plus a ready flag for when Paddle.js has finished initialising.

### Usage notes

Create a client-side token at Paddle > Developer Tools > Authentication. Sandbox tokens start with test_ (use sandbox-vendors.paddle.com). Live tokens start with live_ (use vendors.paddle.com). Set NEXT_PUBLIC_PADDLE_ENV to 'sandbox' or 'production' to match your token. See: https://developer.paddle.com/paddlejs/client-side-tokens