UpgradeModal

UpgradeModal is the confirmation dialog behind UpgradeButton, for when your page owns the open state or confirms a billing action with your own onSubmit. When to use

A plan change confirmation opened from your own button or menu.
A confirm step that shows a quote you read with useUpgradePreview.
Any confirm-then-call flow on a billing page, without BillingProvider, through onSubmit.

UpgradeModal with credits applied, new plan charge, amount due today and next billing date, light theme

Importing UpgradeModal

import { UpgradeModal, type ProrationPreview } from '@nozle-js/react'

Rendering UpgradeModal

Keep the open state yourself and close the dialog in its callbacks. Without onSubmit, confirm calls createCheckout on BillingProvider:

components/upgrade-flow.tsx

import { useState } from 'react'

export function UpgradeFlow({ onClientSecret }: { onClientSecret: (secret: string) => void }) {
  const [open, setOpen] = useState(false)
  const close = () => setOpen(false)
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>Upgrade to Scale</button>
      <UpgradeModal
        isOpen={open}
        planCode="scale"
        onCancel={close}
        onStripeClientSecret={onClientSecret}
        onCheckoutStarted={close}
        onCompleted={close}
        onScheduled={close}
      />
    </>
  )
}

The dialog moves focus in on open and back on close, traps focus, and closes on Escape. It shows a busy state, an error message, and your own title and labels.

What a confirm does

With onSubmit, confirm runs your action. Without it, confirm calls createCheckout with the plan code, return URL and the subscriptionId, quoteId and idempotencyKey you pass, then handles the result:

a Stripe client secret goes to onStripeClientSecret, then onCheckoutStarted fires,
a completed change or a captured Razorpay payment fires onCompleted,
a scheduled result fires onScheduled,
a processing result shows “Payment is processing. Confirmation may take a little while.” in the dialog.

onConfirm fires after confirm finished without an error, by either path. See checkout result types.

Data

preview holds the amounts in major units (dollars, not cents), with separate credit and debit:

const preview: ProrationPreview = {
  credit: 14.5,
  debit: 49.5,
  net: 35,
  currency: 'USD',
  nextBillingDate: '2026-11-01T00:00:00Z',
}

export function UpgradeDialog({ open, close }: { open: boolean; close: () => void }) {
  return <UpgradeModal isOpen={open} planCode="scale" preview={preview} onCancel={close} onCompleted={close} />
}

Live data

The quote from useUpgradePreview is in minor units, so show it as children and pass its quote_id:

import { useSubscription, useUpgradePreview } from '@nozle-js/react'

function money(minor: number | string, currency: string) {
  const format = new Intl.NumberFormat('en-US', { style: 'currency', currency })
  const digits = format.resolvedOptions().maximumFractionDigits ?? 2
  return format.format(Number(minor) / 10 ** digits)
}

export function QuotedUpgrade({ open, close }: { open: boolean; close: () => void }) {
  const subscription = useSubscription()
  const quote = useUpgradePreview(open ? 'scale' : undefined)
  return (
    <UpgradeModal
      isOpen={open}
      planCode="scale"
      subscriptionId={subscription.data?.subscription?.external_id}
      quoteId={quote.data?.quote_id}
      confirmDisabled={!quote.data}
      onCancel={close}
      onCompleted={close}
      onScheduled={close}
    >
      {quote.data && (
        <p>
          Due now: {money(quote.data.amount_due_now_cents, quote.data.currency)}. Effective{' '}
          {new Date(quote.data.effective_at).toLocaleDateString('en-US')}.
        </p>
      )}
    </UpgradeModal>
  )
}

Examples

Proration amounts

With preview, the dialog lists credits applied, the new plan charge, the amount due today and the next billing date.

const preview: ProrationPreview = { credit: 14.5, debit: 49.5, net: 35, currency: 'USD', nextBillingDate: '2026-11-01T00:00:00Z' }

export function UpgradeDialog({ open, close }: { open: boolean; close: () => void }) {
  return <UpgradeModal isOpen={open} planCode="scale" preview={preview} onCancel={close} onCompleted={close} />
}

Your own submit action

With onSubmit, the dialog runs your action instead of createCheckout and needs no BillingProvider.

export function ConfirmSeats({ open, close }: { open: boolean; close: () => void }) {
  return (
    <UpgradeModal
      isOpen={open}
      planCode="team"
      title="Add 5 seats?"
      confirmLabel="Add seats"
      onSubmit={async () => {
        const response = await fetch('/api/billing/seats', { method: 'POST', body: JSON.stringify({ add: 5 }) })
        if (!response.ok) throw new Error('Seats could not be added')
      }}
      onConfirm={close}
      onCancel={close}
    >
      <p>Your next invoice includes 5 more seats.</p>
    </UpgradeModal>
  )
}

Back button

onBack shows a Back button on the left of the actions, for a step that has a previous step.

export function ConfirmStep({ open, back, close }: { open: boolean; back: () => void; close: () => void }) {
  return <UpgradeModal isOpen={open} planCode="scale" onBack={back} onCancel={close} onCompleted={close} />
}

API reference

boolean

required

Shows the dialog. When false nothing renders.

string

required

The plan sent to createCheckout.

() => void

Fires when the Close button is clicked or Escape is pressed (not while busy). Close the dialog here.

string

default:"Confirm plan change"

The dialog title.

string

default:"Confirm"

Text of the confirm button. While busy it reads “Checking subscription…”.

boolean

default:false

Disables the confirm button.

boolean

default:false

Marks the dialog busy from outside: buttons disabled, Escape ignored.

ProrationPreview

Amounts in major units: credit (shown as “Credits applied” only when above 0), debit (“New plan charge”), net (“Due today”), nextBillingDate (an ISO date) and currency (defaults to USD).

ReactNode

Content below the amounts.

string

Formats the amounts and the next billing date. Without it the amounts use en-US and the date uses the browser’s locale.

() => Promise<void>

From React 0.10.0. Your action for the confirm button. When set, createCheckout is not called and BillingProvider is not needed. A rejection shows its message.

string

Sent to createCheckout. Not sent when left out.

string

Sent to createCheckout. Not sent when left out.

string

Sent to createCheckout. Not sent when left out.

string

Sent to createCheckout. Defaults to the current URL.

(clientSecret: string) => void

Fires for an embedded Stripe checkout and receives its client secret.

() => void

Fires after the Stripe client secret was handed over.

() => void

Fires when the change completed, or a Razorpay payment was captured.

() => void

Fires for a scheduled result.

() => void

Fires after confirm finished without an error, by either path.

() => void

Shows a Back button on the left of the actions and fires when it is clicked.

(error: Error) => void

Fires when confirm fails and receives the error. The dialog shows the message.

string

CSP nonce for the dialog’s <style> element.

Appearance

Theme, variables and element overrides. Defaults to the provider’s. See Appearance.

States

State	What shows
Closed (`isOpen={false}`)	Nothing.
Confirming, or `busy`	Buttons disabled, “Checking subscription…” on the confirm button, Escape ignored.
Payment processing	”Payment is processing. Confirmation may take a little while.”
Confirm failed	The error message in the dialog.
No `onSubmit` and no `createCheckout` on the provider	”BillingProvider createCheckout callback is required for checkout”.

The dialog shows Powered by Nozle, unless it is inside another component that already shows it.

Appearance

Element keys

upgradeModal (the backdrop, also class nozle-upgrade-modal), upgradeModal__dialog, upgradeModal__actions.Style them with appearance.elements. See Elements.

UpgradeButton

A button that opens this dialog.

PlanChangeControl

Uses this dialog for its plan list and quote.

Setup

Components

Billing

Entitlements

UpgradeModal

Importing UpgradeModal

Rendering UpgradeModal

What a confirm does

Data

Live data

Examples

Proration amounts

Your own submit action

Back button

API reference

States

Appearance

UpgradeButton

PlanChangeControl

​Importing UpgradeModal

​Rendering UpgradeModal

​What a confirm does

​Data

​Live data

​Examples

​Proration amounts

​Your own submit action

​Back button

​API reference

​States

​Appearance

​Related

UpgradeButton

PlanChangeControl

Importing UpgradeModal

Rendering UpgradeModal

What a confirm does

Data

Live data

Examples

Proration amounts

Your own submit action

Back button

API reference

States

Appearance

Related