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.
Install
pnpm dlx shadcn@latest add @paddle/paddle-helpersyarn dlx shadcn@latest add @paddle/paddle-helpersnpx shadcn@latest add @paddle/paddle-helpersProps
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.
Install
pnpm dlx shadcn@latest add @paddle/paddle-clientyarn dlx shadcn@latest add @paddle/paddle-clientnpx shadcn@latest add @paddle/paddle-clientProps
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
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.