For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

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.

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
pnpm dlx shadcn@latest add @paddle/paddle-helpers
yarn
yarn dlx shadcn@latest add @paddle/paddle-helpers
npm
npx shadcn@latest add @paddle/paddle-helpers

Use an AI agent

Import this component
Import this component from https://developer.paddle.com/r/paddle-helpers.json and open the code for editing. IMPORTANT: preserve the component exactly as-is. Do NOT change colors, CSS variables, Tailwind classes, spacing, fonts, or any visual styles. Do NOT regenerate or restyle the UI. Create files from the registry JSON verbatim and show the code tree.

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.

Install

pnpm
pnpm dlx shadcn@latest add @paddle/paddle-client
yarn
yarn dlx shadcn@latest add @paddle/paddle-client
npm
npx shadcn@latest add @paddle/paddle-client

Use an AI agent

Import this component
Import this component from https://developer.paddle.com/r/paddle-client.json and open the code for editing. IMPORTANT: preserve the component exactly as-is. Do NOT change colors, CSS variables, Tailwind classes, spacing, fonts, or any visual styles. Do NOT regenerate or restyle the UI. Create files from the registry JSON verbatim and show the code tree.

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

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.

Was this page helpful?