Getting started - Whop Docs

Whop Elements are hosted, themeable UI components you embed in your own site. Each element renders in an isolated frame served from Whop’s CDN. You install a thin, fully typed package and the element code stays up to date on its own.

Install

npm install @whop/elements-react @whop/elements

npm install @whop/elements

dependencies: [
    .package(url: "https://github.com/whopio/whopsdk-elements-swift.git", from: "0.1.12")
]

Requirements


React	`^19`, for `@whop/elements-react`.
Content Security Policy	`frame-src https://js.whop.cloud`, plus `script-src https://js.whop.cloud` if you load the script tag.

Elements render in frames served from js.whop.cloud. If your CSP does not allow that origin, you get blank space instead of the element, and the error appears only in the browser console.

Before you start

You need two things:

An accountId. An account ID, prefixed biz_, or a user ID, prefixed user_, for the user’s own data. Payment surfaces take a plan or amount instead, and each element page says which it needs.
A server endpoint that creates an access token, scoped to the elements you mount.

Never put a Whop API key in browser code. It creates tokens, so anyone who opens the browser’s developer tools can read the account. Create the token on your server and send only the token.

Your server calls Create Access Token with the account and the scopes the elements need:

POST https://api.whop.com/api/v1/access_tokens
Authorization: Bearer <api_key>
Content-Type: application/json

{ "company_id": "biz_xxxxxxxx", "scoped_actions": ["company:balance:read"] }


Platform	iOS 18.0+
Toolchain	Swift 6.0
Install	Swift Package Manager

Mount your first element

import { WhopElements, Payments, PaymentElement, AddressElement, CardElement, EmailElement, TaxIdElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <PaymentElement />
        <AddressElement />
        <CardElement />
        <EmailElement />
        <TaxIdElement />
      </Payments>
    </WhopElements>
  );
}

<script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const payments = window.WhopElements().payments.create({ /* options */ });
  payments.create('payment').mount('#payments-payment');
  payments.create('address').mount('#payments-address');
  payments.create('card').mount('#payments-card');
  payments.create('email').mount('#payments-email');
  payments.create('taxId').mount('#payments-taxId');
</script>

import SwiftUI
import WhopElements

/// The SDK calls this again before the token expires, so fetch rather than cache.
final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            WalletScreen()
                .task { await WhopSDK.configure(tokenProvider: WalletTokenProvider()) }
        }
    }
}

struct WalletScreen: View {
    var body: some View {
        ScrollView {
            VStack(spacing: 24) {
                BalanceElement(accountId: "biz_xxxxxxxx")
                ListElement(accountId: "biz_xxxxxxxx")
            }
            .padding()
        }
    }
}

Prefer npm over the script tag? loadWhop() injects the same hosted script and resolves the global constructor:

import { loadWhop } from "@whop/elements";

const whop = (await loadWhop())({ locale: "en" });
const payments = whop.payments.create({ /* options */ });

Authentication

Pass an accessToken when you create the handle. Use one token for the whole handle, not one per element. The handle sends that token to every element under it, so ask for all the scopes you need on that one token. Each element page lists the scopes it reads.

<Ads accountId="biz_xxxxxxxx" accessToken={token}>
  {/* elements */}
</Ads>

const ads = whop.ads.create({ accountId: "biz_xxxxxxxx", accessToken });

The token is a value you set, not a callback the SDK calls. Set a new one before it expires:

ads.update({ accessToken: await createAccessToken() });

If you omit accessToken, requests use the viewer’s session cookie instead. This works only on whop.com. The API does not send Access-Control-Allow-Credentials on cross-origin preflights, so a page on your own domain has no session to fall back to and must pass a token.

Global configuration

Everything you pass at construction applies to every element group created from that instance (a handle’s own options can override per group):

Appearance

Visual customization for every element — theme (light/dark + palettes), variables (CSS custom properties), and classes (per-part style declarations). The color scheme is applied before an element’s first paint, so dark pages never flash light. See Appearance.

"en" | "es" | "zh" | "nl" | "pt" | "de" | "it" | "fr" | "ja" | "pl" | "tr"

Locale for element UI text — one of the app’s built locales; any other value falls back to the default locale. Defaults to "en".

"production" | "sandbox"

Which Whop API environment the elements talk to — "sandbox" targets the sandbox API (test data; no real money moves). Choosing an environment is the only way to change where the elements send what a buyer types, and both environments are Whop’s own. The sandbox environment is not yet generally available. Defaults to "production".

boolean

Whether elements may show toast notifications on your page — brief status messages (“Payment method added”, “Payment failed”) rendered in the bottom-right corner. Set false to turn them off entirely. Defaults to true.

const whop = WhopElements({
  locale: 'es',
  appearance: { theme: { appearance: 'dark', accentColor: 'blue' } }
});

In React, the same object rides <WhopElements appearance={…} locale={…}>.The toasts global is live on this page — the button below sends one through the same rail elements use, themed by this page’s appearance:

What the elements handle, and what you own

Each element fetches its own data and renders its own loading, empty, and error states.You handle navigation and storage. Elements report selections and results as events, and never write to your database.The exception is a flow that leaves the page. Where an element takes a returnUrl, it navigates the tab there, so the buyer can end up off your page. Fulfill from webhooks rather than from a browser callback.Elements run in frames, so only serializable values cross the boundary. There is no shared DOM, and object identity is not preserved.

Troubleshooting

What you see	Why
Blank space instead of the element	Your CSP blocks `js.whop.cloud`. Add it to `frame-src`, and to `script-src` if you use the script tag.
`mount()` does nothing	The selector matched no node. The target must already be in the DOM.
The element loads but stays empty	The token is missing a scope that element reads. Check the scopes listed on the element’s page.
Requests fail on your own domain	No token was passed. The session fallback works only on whop.com.
It worked, then stopped	The token expired. Create a new one and pass it with `update({ accessToken })`.

Available elements

Payments

Collect a payment from a plan_ ID or inline currency and amount.

Checkout

Drives a full hosted checkout for one plan — price summary, promo codes, the currency the buyer pays in, and the whole payment collection surface (the payments elements, composed inside) — against the Whop checkout sessions API.

An advertising account.

Tracking

An account’s tracked audience: everyone its pixel has seen, and every event they performed.

Wallet

Drives an account’s money surfaces.

Websites

An account’s websites: every site built on whop.app plus every domain the Whop Pixel reports, with traffic and attributed revenue per domain.

Appearance: theming, CSS variables, and per-part restyling
Create Access Token: the endpoint your server mints from

Authentication

getToken() is your only integration point, and the SDK calls it again before the token expires, so return a fresh token each time rather than caching one:

final class WalletTokenProvider: WhopTokenProvider {
    func getToken() async -> WhopTokenResponse {
        // your backend, not the Whop API directly
        WhopTokenResponse(accessToken: await myBackend.whopAccessToken())
    }
}

Configure once, anywhere above the elements. WhopSDK is process-wide, so a second call is only needed when the account changes:

await WhopSDK.configure(tokenProvider: WalletTokenProvider())

Chat and DMs authenticate the viewer instead of an account, through OAuth: WhopSDK.configureWithOAuth(appId:).

Theming

.whopTheme(_:) propagates through the SwiftUI environment, so one call themes every element beneath it. Six roles, each a WhopTint:

ListElement(accountId: "biz_xxxxxxxx")
    .whopTheme(WhopTheme(accent: .blue, danger: .red, success: .green))

Defaults are accent: .blue, neutral: .gray, danger: .red, info: .sky, success: .green, warning: .amber. WhopTheme.default is all six. Views follow the system light/dark appearance on their own.

What the elements handle, and what you own

Each view fetches its own data and renders its own loading, empty and error states, including a retry. You own navigation: the selection callbacks hand you a value and never push a screen.

ListElement(accountId: account) { balance in
    path.append(Route.asset(balance.symbol))   // your router, your screen
}

Troubleshooting

What you see	Why
`Authentication failed`	The token is missing, expired, or is an API key rather than an access token. `getToken()` must return a token minted by Create Access Token.
A view stays empty	The token is valid but not scoped for that read. Balances need `company:balance:read`.
`Couldn't load this account`	The `accountId` is not one this token can read.
A chart with no line	Balance history is available only for account IDs prefixed `biz_`, not personal accounts prefixed `user_`.

Available on iOS

The wallet views, each with a live simulator on its page:

BalanceElement: the total balance, its trend, and the range picker
ListElement: the holdings list
ActivityElement: the ledger activity feed

WhopChatView and WhopDMsListView ship in the same package for viewer-authenticated chat. See the README.

​Install

​Requirements

​Before you start

​Requirements

​Before you start

​Mount your first element

​Authentication

​Global configuration

​What the elements handle, and what you own

​Troubleshooting

​Available elements

Payments

Checkout

Ads

Tracking

Wallet

Websites

​Next

​Authentication

​Theming

​What the elements handle, and what you own

​Troubleshooting

​Available on iOS

Install

Requirements

Before you start

Requirements

Before you start

Mount your first element

Authentication

Global configuration

What the elements handle, and what you own

Troubleshooting

Available elements

Next

Authentication

Theming

What the elements handle, and what you own

Troubleshooting

Available on iOS