Skip to main content
This page documents @whop/elements@1.9.0 and @whop/elements-react@1.9.0.
Since v1.0.0.
Mounts inside Checkout. Pass props and callbacks through the create options or React props.
Exclusive. ExpressCheckoutElement is an alternative to CheckoutElement in this Checkout handle. Mount one at a time. Destroy it before mounting another.
Mount inside <Checkout>, which opens the checkout session from your plan, items or checkoutConfiguration and keeps its credential to itself. <Checkout> itself mounts inside <WhopElements>. One press on the button is the whole purchase: there is no confirmation token to hand to your server.

Example data. Open the Playground.

​
Props

​
object | ("apple_pay" | "google_pay" | "paypal_express")[]
wallets as an array is deprecated and will be removed in the next major version. Pass { applePay, googlePay, payPal } with "auto" or "never" instead.
Which wallets may render. Set applePay, googlePay, or payPal to 'never' to leave that button out; each key defaults to 'auto', a filter over what the buyer’s device and the seller actually offer. The element never shows a wallet the device, the served matrix, or the checkout’s payment method configuration cannot back, and the render order stays best-native-first, with PayPal last. A list of wallet types (['apple_pay', 'google_pay']) is still accepted as an allowlist but is deprecated and will be removed in the next major version; an empty list renders nothing (warned in dev builds). Every wallet needs the page’s domain verified as a payment method domain — first-party whop.com pages are pre-approved; on any other site, register and verify the domain or the buttons stay hidden. Offering Google Pay on your own site is subject to the Google Pay API Terms of Service. Defaults to {}.
​
"auto" | "horizontal" | "vertical"
How the buttons stack. auto follows the element’s own container — stacked in narrow containers, side by side in wide ones; horizontal and vertical force one arrangement. Defaults to "auto".

​
Events

Pass callbacks in the create options or React props.

​
onLoaderStart

Runs after the loading skeleton first paints and before onReady.

​
onReady

Runs after the element’s first complete paint.

​
onError

Runs when the element fails to load or crashes. The fallback remains visible. Use code for programmatic handling. sourceKey identifies a failed host-state source.
​
object

​
Methods

Call these on the handle returned by create, or through a React ref.

​
mount

Mounts the element in target and starts loading. React components mount themselves.Parameters
​
string | HTMLElement
required

​
destroy

Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.

​
update

Merges new props into the mounted element. In React, change the component props instead.Parameters
​
Partial<ExpressCheckoutElementProps>
required

​
Styling

Style these parts through appearance.classes. Use camel case or kebab case for property names and include units. Page stylesheets can’t reach the element’s frame. The framework validates each declaration before injecting it.
In React, pass appearance to <Checkout>. Set it globally with WhopElements({ appearance }).

​
Props

​
('apple_pay' | 'google_pay')[]
Which wallets may render, as a filter over what the device offers. The element never shows a wallet the device, the account or the checkout’s payment method configuration cannot back. An empty list renders nothing. Defaults to both.
​
StyleProp<ViewStyle>
Applied to the element’s outer View. For theming, prefer appearance.parts on the provider, which covers every element on this surface. Note the React Native part names are their own set today, not the web’s whop-* class names, so a web appearance object does not port across unchanged.
​
ReactNode
Rendered instead of the built-in skeleton while the element loads.
​
() => void
Fires once the element has settled: the button is up, or the element knows it renders nothing. <Checkout> waits for it, so its own onLoadingChange is usually the one you want.
​
(error: { message: string; code?: string }) => void
A load or configuration failure for this element. The element renders its own error face either way.

​
States

One skeleton pill while the session opens and the device is asked whether it can pay, then the platform’s own Apple Pay or Google Pay button above the Powered by Whop notice. A device with no wallet, a wallet the checkout’s payment method configuration disables, or a plan that is sold out or archived renders nothing. A checkout a sheet cannot honestly finish (a setup, a waitlist join, a transfer, a form question only a page can ask) renders an explanatory face and reports EXPRESS_CHECKOUT_UNAVAILABLE through onError. After the purchase the element shows its outcome: complete, processing, or a Finish payment or Try again press when the payment still needs the buyer.

​
Good to know

  • A device offers one wallet: Apple Pay on iOS, Google Pay on Android. That is why there is no layout prop here: there is never a second button to arrange.
  • The sheet collects what the session still needs: the email when the session has none, a phone number when the seller collects one, and a shipping address for physical goods. A seller who verifies phone numbers gets a code step in a native modal after the sheet closes.
  • On iOS the sheet reprices as the buyer changes card, so tax follows the billing address, and offers a promo code field when the seller allows codes. Google’s Android sheet shows the checkout’s total and has no code field.
  • Your app is never navigated. onComplete on <Checkout> fires once when the purchase stands, with sessionId and receiptId, which is where you move the buyer on. Fulfill from webhooks, not from this callback.
  • 3D Secure and other off-site steps open ASWebAuthenticationSession on iOS and Custom Tabs on Android, and the element polls the payment to rest. returnUrl on <Checkout> must be an https URL you host.
  • Every <Checkout> option is create-time. Changing one after mount reports CHECKOUT_OPTIONS_FROZEN and keeps the original order; give <Checkout> a new key to sell something else.
Wrap your app in <WhopElements getToken={…}> once, then mount <Checkout> around the element. <Checkout> takes plan, items, checkoutConfiguration, quantity, promoCode, affiliateCode, attribution, metadata and returnUrl, plus onComplete, onError, onLoadingChange and fallback. See Getting started and Appearance.