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.
Ads group and opens as a modal overlay: ads.createOverlay('campaign-creator', { … }) — consumer props and on<Event> callbacks both go in the create options.
This element is modal-only — open it with
createOverlay; it has no inline mount.Preview
A live, interactive demo of this element with sample data:Usage
Props
string
A scoped token for the reads and writes — it needs
ad_campaign:create. 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 campaign (
adcamp_…) to open. Empty builds a new one. A draft opens where it was left off; a launched campaign opens in edit mode. Defaults to "".string
The ad group (
adgrp_…) to open in focus, within campaignId. Ignored when the campaign has no such group, and when campaignId is empty. Defaults to "".string
The ad (
ad_…) to open in focus, within adGroupId. Ignored when that group has no such ad, and when adGroupId is empty. Defaults to ""."ads" | "ad-groups" | "campaign-settings"
Which step to open on:
campaign-settings, ad-groups, or ads. The dashboard deep-links this off its own URL; pass it to drop a merchant straight onto the part they came to change. Read once at mount — moving it later will not walk them between steps. Defaults to "campaign-settings".Direct mode only
These props exist only on the in-process (direct-mode) component — the hosted embed never carries them, and the element renders without them.direct mode only
Direct mode only. Renders the billing checklist a first launch must clear.
Events
Pass a callback in the create options (or React prop) to receive these.onExited
The merchant backed out of the builder without launching. Nothing has been discarded — a draft campaign, if one was started, is already saved. An overlay has already closed itself by the time this fires; react to it if your page needs to.
Signature: ((payload: Record<string, never>) => void)
onLaunched
A campaign went live. firstLaunch marks the account’s first ever launched campaign, which is what the dashboard uses to show its welcome state. An overlay has already closed itself; this is where you route onward.
Signature: ((payload: { campaignId: string; firstLaunch: boolean; }) => 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<CampaignCreatorElementProps>) => 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 <Ads>; appearance also applies globally at WhopElements({ appearance }).