Skip to main content
Upcoming. These docs cover unreleased development, ahead of any published release. Use the channel picker at the top of the sidebar for the docs of a published release.
In development, not yet part of a stable release. Belongs to the Tracking group. Render <EventsElement /> inside it (React), or call tracking.create('events', { … }) on the handle (vanilla). Consumer props and on<Event> callbacks both go in the create options / JSX props.

Preview

A live, interactive demo of this element with sample data:

Usage

Props

string
Pin the window to an exact ISO 8601 instant instead of the handle’s period — how a deep link reproduces the precise rows behind a metric. Set both from and to or neither. Defaults to "".
string
The pinned window’s end, as an ISO 8601 instant. Defaults to "".
string
Narrow to events attributed to a traffic source, as a source path — whop:adcamp_…:* for one of the account’s campaigns, ext:*, referrer:*, direct. Defaults to "".
string
Narrow by the utm_source the traffic carried. Defaults to "".
string
Narrow by country, as a two-letter ISO code — US, GB. Defaults to "".
string
Narrow by device class — desktop, mobile, tablet, bot. Defaults to "".
string
Narrow by browser name. Defaults to "".
string
Narrow by operating system name. Defaults to "".
string
Narrow to one person’s journey — a person id, an email, or a visitor cookie. Set, the list ignores the window and shows their whole history. The search box moves this. Defaults to "".
string
Narrow by event name — payment.completed, pixel.lead, pixel.page, or pixel.custom:<name> for a custom event. The same value the ads table’s result counts link with. Defaults to "".

Events

Pass a callback in the create options (or React prop) to receive these.

onPeriodChanged

The viewer moved the window from the period selector. Every surface under the same handle has already followed it; persist it and pass it back as period/customRange on the handle, or the window resets on the next mount. Signature: ((payload: { period: "today" | "yesterday" | "last_7_days" | "last_14_days" | "last_30_days" | "last_90_days" | "all_time" | "custom"; customRange: { from: string; to: string; } | null; }) => void)

onAttributionModelChanged

The viewer changed which touch gets the credit, from the filter row’s Attribution menu. Every surface under the same handle has already re-credited; persist it and pass it back as attributionModel on the handle, or it reverts on the next mount. Signature: ((payload: { attributionModel: "last_touch" | "first_touch"; }) => void)

onFiltersChanged

The viewer moved a filter or the identifier search. Carries the WHOLE filter state whichever moved — mirror it into your own URL and pass it back as props to make the view reproducible. Signature: ((payload: EventsFilterBag) => void)

onPersonOpened

The viewer clicked a person cell and the handle has no links.person to follow — open your own person view with it (personId is the stable per-person key; identifier is the most human-meaningful one the surface has), or pass links.person on the handle to turn the cells into real anchors instead. Signature: ((payload: { identifier: string; personId: string; }) => void)

onLoaderStart

Fired the moment the element’s own loading skeleton has painted inside its frame. This is 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, which is the return of create (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, and it re-renders with the merged props. React consumers never call it; updating the JSX props does the same. Signature: (options: Partial<EventsElementProps>) => void

Styling

This element exposes no targetable class names. Use appearance (theme, accent color, variables) to restyle it.