Upcoming — generated from the latest merged element source; documents unreleased development. Use the channel picker at the top of the sidebar for the docs of a published release.
Websites group. Render <PixelSetupElement /> inside it (React), or call websites.create('pixel-setup', { … }) on the handle (vanilla) — consumer props and on<Event> callbacks both go in the create options / JSX props.
This element can be mounted inline (
create) or opened as a modal overlay (createOverlay).Preview
A live, interactive demo of this element with sample data:Usage
Props
string
The company (
biz_…) whose pixel this is. Required — the snippet, scans and invites all run against it. Defaults to "".string
A scoped token for the scans and the developer invite. Mint it on your server with
POST /v1/access_tokens and set a fresh one before it expires. Omitted, the calls carry the viewer’s own session, which only answers same-origin.string
The page to check, scanned on mount. Leave it blank and the wizard asks for one. Read once at boot, so
update() will not retarget mid-flow — mint a fresh mount for a different page. Defaults to "".string
Optional. An event that must fire on that page (
lead, schedule, view_content, …); the events step blocks until it is detected. Unset, every event is offered and none is required. Events Whop records server-side (purchase, subscribe, trials, checkout steps) are ignored. Read once at boot. Defaults to "".string
A URL the destination redirects to, when the event fires there instead. The merchant can also set one in the wizard — listen for
redirectUrlChanged and pass it back next time. Defaults to ""."events" | "install"
Where the wizard opens: the install step, or straight onto
events when the pixel is already there and only the conversion event is missing. Defaults to "install".boolean
Open on the “why a pixel” splash. Turn it off where the merchant already knows why they are here — a campaign flow that sends them in mid-launch — and the wizard opens straight on the install step. Defaults to
true.boolean
Offer the “Invite a developer to install it” path. Hide it where the people using your embed should not be inviting members onto the Whop team behind it. Defaults to
true.Events
Pass a callback in the create options (or React prop) to receive these.onRedirectUrlChanged
The merchant set or cleared a redirect URL in the wizard. Persist it and pass it back as redirectUrl next time.
Signature: ((payload: { url: string; }) => void)
onScanned
A pixel scan settled. Fires for every URL the wizard checks, so your own install badge can follow it. primary marks the page being set up: the funnel checker scans whatever else the merchant lists, other hostnames included, so gate on it before you treat a result as being about their site.
Signature: ((payload: { url: string; status: "installed" | "missing" | "unreachable"; installed: boolean; primary: boolean; }) => void)
onFinished
Done was pressed. Re-check the page yourself — this says the wizard finished, not that your requirements are met.
Signature: ((payload: Record<string, never>) => void)
onEventVerified
The merchant walked their funnel with “Verify live” and this event fired — proof it is wired where a server-side scan cannot reach.
Signature: ((payload: { url: string; event: string; }) => void)
onLoaderStart
Fired the moment the element’s own loading skeleton has painted inside its frame — the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes onReady; most consumers only need onReady.
Signature: (() => void)
onReady
Fired once the element has booted and painted its first complete frame.
Signature: (() => void)
onError
Fired when the element fails to load or crashes; the element shows its own error fallback. message is human-readable; framework refusals also carry code (e.g. HOST_SOURCE_FAILED, with sourceKey naming the failed hostState key) so hosts can switch on codes, never message text.
Signature: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)
Methods
Call these on the element handle — the return ofcreate (vanilla) or the component ref (React).
mount
Place the element on the page: appends its container to target (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it — the component mounts itself.
Signature: (target: string | HTMLElement) => void
destroy
Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it — unmounting the component does it.
Signature: () => void
update
Change this element’s consumer props after mount — it re-renders with the merged props. React consumers never call it — updating the JSX props does the same.
Signature: (options: Partial<PixelSetupElementProps>) => void
Styling
Each part below is a stable class name — safe to depend on. Restyle a part by mapping its class to a style declaration object underappearance.classes (properties camelCase or kebab-case, values as strings with units — the same shape as React’s style prop). The element renders in its own frame, so page stylesheets can’t reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.
appearance prop on <Websites>; appearance also applies globally at WhopElements({ appearance }).