Components

Declarative wrappers over the hooks. They cover the most common patterns — 80% of integrations skip useEffect boilerplate. For the rest, reach for the hooks directly.

<PaywallGate>

Declarative gate: loading → fallback → children. Powered by usePaywallAccess.

<PaywallGate
  loading={<Skeleton />}
  fallback={({ open }) => <button onClick={open}>Upgrade</button>}
>
  <PremiumFeature />
</PaywallGate>

Props

interface BlockedRenderArgs {
  result: Extract<PaywallAccessResult, { access: 'blocked' }>;
  open: () => void;
}

Patterns

<PaywallGate fallback={<UpgradeCTA />}>
  <PremiumFeature />
</PaywallGate>

<PaywallGate openOnBlocked>
  <PremiumFeature />
</PaywallGate>

<PaywallGate
  loading={<Skeleton />}
  fallback={({ open, result }) => (
    <Card>
      <h3>Pro feature locked</h3>
      <p>Your trial ended {timeSince(result.trial?.expiresAt)} ago.</p>
      <button onClick={open}>Continue with Pro</button>
    </Card>
  )}
>
  <PremiumFeature />
</PaywallGate>

function PremiumFeatureGated() {
  const access = usePaywallAccess();
  const paywall = usePaywall();
 
  if (access.status === 'loading') return <Skeleton />;
 
  if (access.result.access === 'granted') {
    return <PremiumFeature />;
  }
 
  // Custom: show "Try trial" if the user hasn't had a trial yet
  if (!access.result.user?.had_previous_trial) {
    return <button onClick={() => paywall?.open()}>Try free</button>;
  }
  return <button onClick={() => paywall?.open()}>Upgrade</button>;
}

<PaywallButton>

Sugar over usePaywall().open(). Renders a native <button> by default and forwards every HTML attribute.

<PaywallButton className="btn-primary">
  Upgrade
</PaywallButton>

Props

Custom element via render

<PaywallButton render={({ open, ready }) => (
  <MyFancyButton onClick={open} disabled={!ready}>
    Upgrade
  </MyFancyButton>
)} />

Radix-style asChild via render prop. Before Provider mount ready: false — the button should be disabled, otherwise the click is a no-op (no instance yet).

Mode variants

<PaywallButton>Upgrade</PaywallButton>                    {/* opens the paywall layout */}
<PaywallButton mode="support">Need help?</PaywallButton>  {/* openSupport() */}
<PaywallButton mode="signin">Sign in</PaywallButton>      {/* openSignin() */}
<PaywallButton mode="signup">Create account</PaywallButton> {/* openSignup() */}

Renewal flow

<PaywallButton renew>
  Renew subscription
</PaywallButton>

The paywall opens, skipping the has_active_subscription check — createCheckout() is called with ignoreActivePurchase: true. Use on the “Renew/Upgrade plan” button in the customer portal.

Direct checkout (priceId)

When you render your own pricing page (cards / table) and want the click to go straight to the hosted checkout — skipping the plan-picker step in the modal — pass priceId:

import { usePaywallPrices, PaywallButton } from '@monetize.software/sdk-react';
 
function PricingCards() {
  const { prices } = usePaywallPrices();
  return prices?.map((p) => (
    <Card key={p.id}>
      <h3>{p.label}</h3>
      <PaywallButton priceId={p.id} className="btn-primary">
        Get this plan
      </PaywallButton>
    </Card>
  ));
}

The button shows busy state automatically. While the SDK is preparing the checkout (bootstrap → gates → createCheckout) — typically 200–500 ms — the button is disabled and exposes aria-busy="true". No modal-flash. Once the hosted-checkout tab opens, the modal mounts directly into the awaiting_payment view. Use the render prop if you need to draw your own spinner:

<PaywallButton
  priceId={p.id}
  render={({ open, ready, processing }) => (
    <MyFancyButton onClick={open} disabled={!ready || processing}>
      {processing ? <Spinner /> : 'Get this plan'}
    </MyFancyButton>
  )}
/>

What the modal still does for you, on demand:

• Auth-gate when checkout_mode: 'preauth' is configured and there’s no signed-in user — the signin form appears, and after success the flow auto-resumes into /start-checkout.
• Popup-blocked fallback — if window.open() returned null (lost transient activation after async signin, aggressive mobile blockers), the modal shows an inline “Open checkout” retry under a fresh user gesture.
• Awaiting-payment screen — the modal stays mounted while the user pays in the new tab, with an “I’ve paid” verify button and “Open checkout again” recovery.

Without a modal at all:

• Already-paid — if the user already has an active subscription (detected via cached user, fresh bootstrap, the preauth signin, or a 409 hasActivePurchase from the backend), the SDK emits purchase_completed { restored: true } and stays headless. The host surfaces that however it likes (toast, redirect, badge update via usePaywallUser).
• Errors — error is emitted (identity.email missing, bootstrap failure, createCheckout rejection); the modal never appears.

Offers (usePaywallOffer(priceId)) automatically thread their offerId into /start-checkout — required for duration_minutes-offers whose countdown lives in clientStorage (the backend can’t validate the timer, so without an explicit offerId the discount would not apply on the hosted checkout).

Under the hood this calls paywall.checkout(priceId, opts) — the same OpenOptions apply (identity, renew, skipTrial, skipVisibility).

<PaywallSupportButton>

Shortcut for <PaywallButton mode="support">. Useful for UI conventions (“Help” in a page corner).

<PaywallSupportButton>
  Need help?
</PaywallSupportButton>

Takes the same HTML attributes as <PaywallButton>, minus mode (fixed) and renew/skipTrial (irrelevant for support).

Composition: feature gate + CTA

A typical shape for a premium page:

function AISummaryPage() {
  return (
    <main>
      <h1>AI Summary</h1>
 
      <PaywallGate
        loading={<Skeleton />}
        fallback={({ open }) => (
          <section>
            <p>This feature is included in Pro.</p>
            <PaywallButton>Start free trial</PaywallButton>
          </section>
        )}
      >
        <AISummaryWidget />
      </PaywallGate>
 
      <footer>
        <PaywallSupportButton>Help</PaywallSupportButton>
      </footer>
    </main>
  );
}

<PaywallGate> controls access, <PaywallButton> opens the modal, <PaywallSupportButton> is a separate path to support. No useEffect chains, everything declarative.

SSR

All three components render safely on the server:

• <PaywallGate> renders the loading prop (or null) — paywall.getAccess() is not invoked on the server.
• <PaywallButton> renders a native <button> with disabled until the instance is ready.
• <PaywallSupportButton> — same.

After the Provider mounts on the client, usePaywallAccess() fires its first getAccess() and the tree re-renders.

Next steps

• Hooks — the primitives underneath the components; use them for custom scenarios.
• Quickstart Web — end-to-end React integration.
• Customer portal — list/cancel/renew without <PaywallGate>.