> ## 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.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# PeopleElement

> Toutes les personnes vues par le compte — visiteurs et clients identifiés à partir de l'activité du pixel, avec leur source, leurs dépenses et leurs compteurs d'activité. Recherchez, filtrez par source, événement, zone géographique ou appareil, triez n'importe quelle colonne et parcourez les pages. Un clic sur une ligne suit `links.person` lorsque le handle le configure, et vous est sinon renvoyé sous forme de `personOpened`.

> [!NOTE]
>
> Cette page documente `@whop/elements@1.10.0` et `@whop/elements-react@1.10.0`.

*Depuis `v1.0.0`.*

Se monte à l'intérieur de [`Tracking`](https://docs.whop.com/fr/elements/latest/tracking/overview). `accountId` et `accessToken` en proviennent. Transmettez les props et les callbacks via les options de création ou les props React.

```tsx React theme={null}
import { WhopElements, Tracking, PeopleElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Tracking /* options */>
        <PeopleElement onPeriodChanged={(e) => console.log(e)} onAttributionModelChanged={(e) => console.log(e)} onFiltersChanged={(e) => console.log(e)} onSortChanged={(e) => console.log(e)} onPersonOpened={(e) => console.log(e)} />
      </Tracking>
    </WhopElements>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const tracking = window.WhopElements().tracking.create({ /* options */ });
  tracking.create('people', {
    onPeriodChanged: (e) => console.log(e),
    onAttributionModelChanged: (e) => console.log(e),
    onFiltersChanged: (e) => console.log(e),
    onSortChanged: (e) => console.log(e),
    onPersonOpened: (e) => console.log(e)
  }).mount('#tracking-people');
</script>
```

Données d'exemple. [Ouvrir le Playground](https://docs.whop.com/fr/elements/latest/tracking/overview#playground).

## Props

**source** `string`

Limite aux personnes acquises par une source de trafic, sous forme de chemin de source — `whop:adcamp_…:*` pour l'une des campagnes du compte, `ext:*` pour les annonces diffusées ailleurs, `referrer:*`, `direct`. C'est la même valeur que celle utilisée par les liens des compteurs de clics du tableau des annonces : une page peut donc l'hydrater directement à partir de sa propre URL. Par défaut : `""`.

**eventName** `string`

Limite aux personnes ayant effectué un événement, par son nom — `payment.completed`, `pixel.lead`, `pixel.page`. Par défaut : `""`.

**customEvent** `string`

Limite aux personnes ayant effectué un événement pixel personnalisé, par son nom personnalisé. S'utilise avec un `eventName` vide. Par défaut : `""`.

**utmSource** `string`

Filtre selon le `utm_source` porté par leur trafic. Séparez plusieurs valeurs par des virgules pour correspondre à l'une d'entre elles. Par défaut : `""`.

**country** `string`

Filtre par code pays ISO 3166-1 alpha-2, comme `US` ou `GB`. Par défaut : `""`.

**device** `string`

Filtre par catégorie d'appareil — `desktop`, `mobile`, `tablet`, `bot`. Par défaut : `""`.

**browser** `string`

Filtre par nom de navigateur. Par défaut : `""`.

**os** `string`

Filtre par nom de système d'exploitation. Par défaut : `""`.

**hasPurchased** `string`

`true` pour les clients uniquement, `false` pour les personnes n'ayant jamais acheté, vide pour tout le monde. Par défaut : `""`.

**query** `string`

Le filtre appliqué par le champ de recherche — un nom, un e-mail ou un identifiant. Par défaut : `""`.

**audienceId** `string`

Limite à une audience enregistrée (`adaud_…`) construite à partir de filtres de personnes. Le menu de filtre d'audience modifie cette valeur. Par défaut : `""`.

**eventFrom** `string`

Fixe la période des événements pour les filtres `source`/`eventName` sur un instant ISO 8601 exact au lieu du `period` du handle. Définissez à la fois `eventFrom` et `eventTo`, ou aucun des deux. Par défaut : `""`.

**eventTo** `string`

La fin de la période d'événements fixée, sous forme d'instant ISO 8601. Par défaut : `""`.

**sort** `string`

La colonne triée : `name`, `email`, `ltv`, `purchase_count`, `event_count`, `first_seen_at`, `last_seen_at`. Par défaut : `"last_seen_at"`.

**dir** `"asc" | "desc"`

Le sens du tri. Par défaut : `"desc"`.

## Événements

Transmettez les callbacks dans les options de création ou dans les props React.

### `onPeriodChanged`

L'utilisateur a modifié la période depuis le sélecteur de période. Chaque surface du même handle a déjà suivi ce changement ; conservez-la et renvoyez-la comme `period`/`customRange` sur le handle, sinon la période est réinitialisée au prochain montage.

**payload** `object`

**propriétés**

**period** `string` *required*

L'une des valeurs `"today"`, `"yesterday"`, `"last_7_days"`, `"last_14_days"`, `"last_30_days"`, `"last_90_days"`, `"all_time"` ou `"custom"`.

**customRange** `object | null` *required*

**propriétés**

**from** `string` *required*

**to** `string` *required*

### `onAttributionModelChanged`

L'utilisateur a changé le point de contact qui reçoit l'attribution, depuis le menu Attribution de la ligne de filtres. Chaque surface du même handle a déjà recalculé l'attribution ; conservez la valeur et renvoyez-la comme `attributionModel` sur le handle, sinon elle est rétablie au prochain montage.

**payload** `object`

**propriétés**

**attributionModel** `"last_touch" | "first_touch"` *required*

### `onFiltersChanged`

L'utilisateur a modifié un filtre, le champ de recherche ou le sélecteur d'audience. Transporte l'état complet des filtres, quel que soit celui qui a changé — reflétez-le dans votre propre URL et renvoyez-le sous forme de props pour rendre la vue reproductible.

**payload** `PeopleFilterBag`

**propriétés**

**source** `string` *required*

**eventName** `string` *required*

**customEvent** `string` *required*

**utmSource** `string` *required*

**country** `string` *required*

**device** `string` *required*

**browser** `string` *required*

**os** `string` *required*

**hasPurchased** `string` *required*

**query** `string` *required*

**audienceId** `string` *required*

**eventFrom** `string` *required*

**eventTo** `string` *required*

### `onSortChanged`

L'utilisateur a trié une colonne. Conservez le tri et renvoyez-le comme `sort`/`dir`, sinon il est réinitialisé au prochain montage.

**payload** `object`

**propriétés**

**sort** `string` *required*

**dir** `"asc" | "desc"` *required*

### `onPersonOpened`

L'utilisateur a cliqué sur une ligne de personne et le handle n'a aucun `links.person` à suivre. Présentez l'élément `person` avec cette valeur, par ex. `createOverlay("person", { identifier: payload.personId })` (`personId` est la clé stable propre à chaque personne ; `identifier` est la plus parlante dont dispose la surface), ou transmettez plutôt `links.person` sur le handle pour transformer les lignes en véritables liens.

**payload** `object`

**propriétés**

**identifier** `string` *required*

**personId** `string` *required*

### `onLoaderStart`

S'exécute après le premier affichage du squelette de chargement et avant `onReady`.

### `onReady`

S'exécute après le premier affichage complet de l'élément.

### `onError`

S'exécute lorsque l'élément ne parvient pas à se charger ou plante. L'affichage de repli reste visible. Utilisez `code` pour une gestion programmatique. `sourceKey` identifie une source d'état hôte en échec.

**e** `object`

**propriétés**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## Méthodes

Appelez-les sur le handle renvoyé par `create`, ou via une `ref` React.

### `mount`

Monte l'élément dans `target` et démarre le chargement. Les composants React se montent eux-mêmes.

**Paramètres**

**target** `string | HTMLElement` *required*

### `destroy`

Supprime l'élément et libère son frame et ses abonnements. Vous pouvez l'appeler plusieurs fois. React supprime l'élément automatiquement.

### `update`

Fusionne de nouvelles props dans l'élément monté. Avec React, modifiez plutôt les props du composant.

**Paramètres**

**options** `Partial\<PeopleElementProps\>` *required*

## Style

Cet élément n'expose pas de noms de classes pour le style. Utilisez `appearance` (thème, couleur d'accent, variables) pour modifier son apparence.
