> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ads

> An advertising account's dashboard. `report-chart` draws what the account spent and what it got back over a window; the campaigns table and the dashboard that welds them together follow. Scope it to a company with `accountId` — the ad account underneath is assigned server-side and never surfaces here.

<Info>**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.</Info>

*In development — not yet part of a stable release.*

## Playground

Assemble the elements with sample data — drive the controls, add and arrange elements, and watch events fire live:

<div data-whop-demo-shell style={{ position: "relative", minHeight: "480px", transition: "min-height 200ms ease" }}>
  <div data-whop-demo-skeleton style={{ position: "absolute", inset: "0", borderRadius: "12px", background: "rgba(140, 140, 140, 0.12)", pointerEvents: "none", transition: "opacity 200ms ease" }} />

  <div data-whop-demo-native="playground:ads" data-whop-elements-version="" style={{ position: "relative" }} />
</div>

## Usage

<div data-whop-usage="ads/playground">
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Ads } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Ads /* options */>
            {/* mount elements here */}
          </Ads>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const ads = window.WhopElements().ads.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.ads.create({ … })` — or as props on `<Ads>` in React.

<ResponseField name="accountId" type="string">
  The company (`biz_…`) whose advertising this reads. Required. This is the Whop account, not an ad account. Defaults to `""`.
</ResponseField>

<ResponseField name="period" type="&#x22;today&#x22; | &#x22;yesterday&#x22; | &#x22;last_7_days&#x22; | &#x22;last_14_days&#x22; | &#x22;last_30_days&#x22; | &#x22;last_90_days&#x22; | &#x22;all_time&#x22; | &#x22;custom&#x22;">
  The window every surface reports on: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days`, `all_time`, or `custom` (pair it with `customRange`). The chart carries the picker, and it moves this — so a host can drive the window and read it back off `periodChanged`. Defaults to `"last_14_days"`.
</ResponseField>

<ResponseField name="customRange" type="{ from: string; to: string; } | null">
  The explicit window, as ISO 8601 instants, used when `period` is `custom`. Ignored otherwise. Defaults to `null`.
</ResponseField>

<ResponseField name="timezone" type="string">
  The IANA zone every figure is reported in — `America/New_York`, `Europe/London`. Unset, it defaults to the account's `preferences.ads_scheduling_timezone`. Either way that zone stays available in the chart's timezone picker. Defaults to `""`.
</ResponseField>

<ResponseField name="currency" type="string">
  The ISO currency every amount is converted to and labelled in — `usd`, `eur`. Unset, it defaults to the account's `preferences.ads_reporting_currency`. Defaults to `""`.
</ResponseField>

<ResponseField name="campaignIds" type="string[]">
  Narrow reporting to these ad campaigns (`adcamp_…`). Empty reports on the whole account. Overridden by `adGroupIds` or `adIds` when either is set. **Pass one id for an exact figure:** the reporting API scopes by a single source path, so where more than one is given the chart reports on the first alone. Defaults to `[]`.
</ResponseField>

<ResponseField name="adGroupIds" type="string[]">
  Narrow reporting to these ad groups (`adgrp_…`). Takes precedence over `campaignIds`. Same single-id caveat. Defaults to `[]`.
</ResponseField>

<ResponseField name="adIds" type="string[]">
  Narrow reporting to these ads (`ad_…`). The narrowest filter — takes precedence over both others. Same single-id caveat. Defaults to `[]`.
</ResponseField>

<ResponseField name="getToken" type="(() => Promise<string>)">
  Called on your page to supply the bearer every API call is made with. It must resolve a credential scoped to `accountId`.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements — overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text — one of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onLoadingChange`

Fired when the grouped loading state changes — `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Ads handle — the return of `whop.ads.create({ … })` (vanilla) or `useAds()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it — updating the namespace component's props does the same.

**Signature:** `(options: Partial<AdsOptions>) => void`

## Elements

The elements this group mounts — each has its own page:

<CardGroup cols={2}>
  <Card title="ReportChartElement" href="/elements/upcoming/ads/report-chart">
    An advertising account’s performance charted over a window you choose, with a picker for which metric to plot — spend, impressions, clicks, or any conversion the account records. Read-only, and the chart only: headline figures belong to whatever surface composes this.
  </Card>
</CardGroup>