Skip to main content
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 Payments. Transmettez les props et les callbacks via les options de création ou les props React. Conservez le handle créé, ou la ref React, pour appeler validate() et getValues().
Un par mode. Montez un <AddressElement /> pour chaque valeur de mode sous un même handle Payments. Un second montage avec le même mode est refusé. Le mode d’un élément est défini à sa création ; pour le modifier, détruisez l’élément et créez-en un nouveau.
Se monte à l’intérieur d’un scope WhopPayments. Collecte l’adresse de facturation au format propre au pays sélectionné, et le contrôleur la lit pour la génération du jeton, que vous la liiez ou non.
Montez-le à l’intérieur de <Payments>, qui gère le débit et le jeton de confirmation. <Payments> se monte lui-même à l’intérieur de <WhopElements>. Il affiche l’adresse de facturation au format du pays de l’acheteur et la publie auprès du provider, de sorte que createConfirmationToken la récupère sans qu’on lui transmette quoi que ce soit.

Données d’exemple. Ouvrir le Playground.

Props

"billing" | "shipping"
L’adresse collectée : billing (par défaut) ou shipping. Définit aussi la finalité de l’autocomplétion du navigateur. Vous pouvez en monter un de chaque sous un même handle. Les informations de facturation proviennent de l’élément de facturation, ou de l’élément de livraison lorsqu’aucun élément de facturation n’est monté. Par défaut : "billing".
"split" | "none" | "combined"
La ligne du nom : un seul champ de nom complet (par défaut), des champs prénom/nom séparés, ou aucun. Par défaut : "combined".
"never" | "toggle" | "always"
Ligne d’adresse 2 : toujours visible (par défaut), révélée par un bouton texte (toggle), ou jamais collectée. Par défaut : "always".
object
Valeurs initiales appliquées une fois avant le premier affichage (address.country est un code pays ISO 3166-1 alpha-2). Prévalent sur la détection du pays par IP.
"full" | "compact" | "wrap"
full (par défaut) empile des champs avec libellé. compact regroupe des champs dont le libellé sert de placeholder dans une seule bordure. wrap conserve les champs séparés de full et place aussi la ville, l’État et le code postal côte à côte. Ceux-ci, ainsi que les paires que full place déjà côte à côte (prénom et nom, organisation), tiennent autant que possible sur une ligne selon la largeur et passent à la ligne lorsqu’elle se réduit. Par défaut : "full".
"above" | "floating"
above (par défaut) garde chaque libellé en dehors de son champ : au-dessus dans la disposition full, comme placeholder dans compact. floating utilise chaque libellé comme placeholder de son champ, dans les deux dispositions, puis affiche un petit libellé au-dessus du texte saisi dès que le champ a une valeur. Par défaut : "above". Depuis v1.5.0.
"minimal" | "full"
full (par défaut) suit le format d’adresse complet du pays sélectionné. minimal ne collecte que le pays et le code postal. name ajoute indépendamment les champs de nom requis. Définissez name sur none pour les omettre. Cet élément n’ajoute pas les champs requis par un moyen de paiement. La confirmation par carte nécessite un nom, un pays et un code postal, donc gardez name activé ou transmettez billingDetails.name. Par défaut : "full".
"none" | "name" | "name_with_type"
Champs d’organisation : aucun (par défaut), nom uniquement, ou nom avec un sélecteur entreprise/particulier. Par défaut : "none".
boolean
Définit le pays par défaut à partir de l’IP de l’acheteur (résolue avant le premier affichage). Se rabat sur le countryHint du contrôleur, puis sur US. Par défaut : true.
string[]
Codes pays ISO 3166-1 alpha-2 autorisés. Avec un seul code, le sélecteur reste visible mais ne propose que ce pays.
boolean
Active les suggestions Google Places pour l’adresse postale. Si aucune correspondance n’apparaît ou si Places est bloqué, la liste indique l’absence de correspondance et permet aux acheteurs de saisir l’adresse manuellement. Sur téléphone, les suggestions s’ouvrent en plein écran depuis un bouton de recherche dans le champ de rue plutôt qu’en dessous, où le clavier les masquerait. Définissez false pour un champ de saisie simple. Par défaut : true.
boolean
Affiche tous les champs d’adresse dès le départ. Par défaut (false), le formulaire s’ouvre avec l’adresse postale et révèle le reste une fois que l’acheteur choisit une suggestion, saisit une adresse ou choisit de la saisir manuellement. Par défaut : false. Depuis v1.6.0.
object[]
Champs supplémentaires affichés avec le formulaire d’adresse. Les valeurs sont validées et émises dans la map custom distincte.
string
Pays de repli après defaultValues et la détection par IP. Utilisez un code ISO 3166-1 alpha-2. Une valeur vide se rabat sur US. Par défaut : "".

Événements

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

onChange

Se déclenche lorsque l’adresse change. complete vaut true lorsque tous les champs propres au pays et les champs personnalisés requis sont valides. address suit les noms de billing_details du jeton de confirmation, y compris postal_code. country est un code ISO 3166-1 alpha-2. Les valeurs personnalisées se trouvent dans custom.
object

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

Méthodes

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

validate

Valide le formulaire, révèle toutes les erreurs inline et ne lève jamais d’exception. Renvoie complete, address et errors. errors est vide exactement lorsque complete vaut true. Les clés utilisent les noms du contrat comme postal_code et line1, custom:<key> pour les champs personnalisés, et form de manière transitoire pendant le chargement.Renvoie Promise<object>
boolean
requis
object
requis
Record<string, string>
requis

getValues

Renvoie address et custom sans validation ni affichage des erreurs.Renvoie Promise<object>
object
requis
Record<string, string>
requis

mount

Monte l’élément dans target et démarre le chargement. Les composants React se montent eux-mêmes.Paramètres
string | HTMLElement
requis

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
Partial<AddressElementProps>
requis

Style

Stylisez ces parties via appearance.classes. Utilisez le camel case ou le kebab case pour les noms de propriétés et incluez les unités. Les feuilles de style de la page ne peuvent pas atteindre le frame de l’élément. Le framework valide chaque déclaration avant de l’injecter.
Avec React, transmettez appearance à <Payments>. Définissez-la globalement avec WhopElements({ appearance }).

Paramètres

Binding<PostalAddress>?
Relit l’adresse collectée. Le contrôleur la collecte dans tous les cas.
Binding<Bool>?
Vaut true dès que chaque champ requis par le pays est rempli et valide.
WhopAddressElement.Mode
.billing ou .shipping. Shipping demande au clavier des champs de livraison. Par défaut : .billing.
WhopAddressElement.Layout
.full ajoute un libellé à chaque champ et les empile ; .compact déplace les libellés dans les placeholders. Par défaut : .full.
WhopAddressElement.Scope
.full collecte le format complet du pays ; .minimal ne collecte que le pays et le code postal. Par défaut : .full.
WhopAddressElement.NameFields
.combined pour un seul champ de nom complet, .split pour le prénom et le nom, .none pour omettre le nom. Par défaut : .combined.
WhopAddressElement.OrganizationFields
.none, .name pour un nom d’organisation, ou .nameWithType pour demander aussi s’il s’agit d’une entreprise ou d’un particulier. Par défaut : .none.
WhopAddressElement.Line2Field
.always affiche la deuxième ligne, .toggle la révèle avec un bouton, .never l’omet. Par défaut : .toggle.
PostalAddress?
Valeurs de départ. Son country est un code ISO 3166-1 alpha-2 et prévaut sur la détection.
Bool
Démarre sur le pays de l’acheteur lorsque vaut true. Se rabat sur countryHint, puis sur le pays de la devise du débit, puis sur US. Par défaut : true.
[String]?
Limite le sélecteur à ces codes ISO 3166-1 alpha-2, à l’intersection de la contrainte propre au moyen sélectionné.
String?
Valeur de repli ISO 3166-1 alpha-2 pour la chaîne de détermination du pays.
Bool
Suggestions de rue pendant la saisie de l’acheteur. Lorsqu’elle est désactivée, il n’y a rien à choisir, donc tous les champs s’affichent dès le départ. Par défaut : true.

PostalAddress

Ce que renvoie une sélection :
  • country: String : ISO 3166-1 alpha-2, en majuscules
  • line1 / line2 / city / state / postalCode : String?, au format propre au pays
  • name / firstName / lastName : String?, selon le mode name
  • organization / organizationType : String?, selon le mode organization

États

Le formulaire s’affiche immédiatement. Avec l’autocomplétion activée et le scope .full, les champs de localité apparaissent après une suggestion ou une saisie manuelle ; désactivez-la et tous les champs s’affichent d’un coup. Les erreurs apparaissent à la première tentative de confirmation, puis en direct.

Bon à savoir

  • MapKit fournit les suggestions de rue directement sur l’appareil. Whop ne voit jamais la requête de l’acheteur pendant la saisie.
  • defaultValues.country prévaut sur la détection. La détection se rabat sur countryHint, puis sur le pays de la devise du débit, puis sur US.
  • allowedCountries est croisé avec la contrainte de pays de facturation propre au moyen sélectionné, de sorte qu’un moyen qui n’accepte qu’un seul pays restreint le sélecteur de lui-même.
  • PostalAddress utilise les clés billing_details du jeton de confirmation, donc le même JSON fonctionne sur toutes les plateformes.

Installation

Montez-le à l’intérieur d’un scope WhopPayments(accountID:charge:), qui crée le contrôleur et le transmet à son contenu. payments.buyer est l’acheteur connecté dès qu’une connexion par e-mail en a authentifié un. WhopBrandingElement doit aussi être à l’écran, car Whop est le marchand officiel (merchant of record) de ces ventes et createConfirmationToken refuse sans lui. Stylisez avec .whopElementsAppearance(_:). Le module est Elements, et non WhopElements du SDK wallet. Consultez Premiers pas et Apparence.

Props

'billing' | 'shipping'
Finalité de l’autocomplétion. Par défaut : billing.
'full' | 'compact'
full ajoute un libellé à chaque champ et les empile. compact déplace les libellés dans les placeholders. Par défaut : full.
'full' | 'minimal'
full suit le format complet du pays. minimal ne collecte que le pays et le code postal. Par défaut : full.
'combined' | 'split' | 'none'
Un seul champ de nom complet, prénom et nom, ou aucun champ de nom. Par défaut : combined.
'none' | 'name' | 'name_with_type'
Indique s’il faut collecter une organisation, et s’il faut aussi demander s’il s’agit d’une entreprise ou d’un particulier. Par défaut : none.
'toggle' | 'always' | 'never'
La façon dont la deuxième ligne d’adresse apparaît. Par défaut : toggle, qui affiche un bouton « Add address line 2 ».
string[]
Limite le sélecteur de pays à ces codes ISO 3166-1 alpha-2. La liste de pays propre à un moyen de paiement sélectionné la restreint davantage, sans jamais l’élargir.
boolean
Définit le pays par défaut à partir de l’IP de l’acheteur.
string
Pays de repli après defaultValues et la détection par IP. ISO 3166-1 alpha-2.
{ name?: string; address?: Partial<EmittedAddress> }
Valeurs initiales appliquées une fois au montage, pour une session reprise.
CustomFieldSpec[]
Champs supplémentaires affichés à une position déclarée (after_name, after_organization, before_country, after_address). Un champ obligatoire conditionne complete.
(payload: AddressChangePayload) => void
Se déclenche à chaque modification avec l’instantané courant.
StyleProp<ViewStyle>
Appliqué à la View externe de l’élément. Pour la personnalisation du thème, préférez appearance.parts sur le provider, qui couvre tous les éléments de cette interface. Notez que les noms de parties React Native forment aujourd’hui leur propre ensemble, distinct des noms de classes whop-* du web : un objet appearance web ne peut donc pas être repris tel quel.
ReactNode
Affiché à la place du squelette intégré pendant le chargement de l’élément.
() => void
Se déclenche une fois que l’élément est interactif. <Payments> les regroupe, donc c’est généralement son propre onLoadingChange qu’il vous faut.
(error: { message: string; code?: string }) => void
Un échec de chargement ou de configuration pour cet élément. L’élément affiche sa propre vue d’erreur dans tous les cas.

AddressChangePayload

Ce que renvoie onChange :
  • complete: boolean : chaque champ requis par le pays est rempli et valide
  • address: EmittedAddress : ce que l’acheteur a saisi jusqu’à présent
  • custom: Record<string, string> : les valeurs des customFields que vous avez déclarés

États

Un squelette de trois champs pendant le chargement du catalogue de pays, puis le formulaire. Changer de pays réorganise les champs, car le format est celui du pays, et non un ensemble fixe. onChange signale complete lorsque chaque champ requis par le pays est rempli et valide.

Bon à savoir

  • Le pays est défini par défaut à partir de l’IP de l’acheteur lorsque detectCountry est activé, puis countryHint, puis US. defaultValues.address.country prévaut sur les trois.
  • autocomplete est activé par défaut, comme sur le web, mais il est fourni par le géocodeur de la plateforme plutôt que par Google Places : il ne nécessite donc ni clé API, ni compte, ni dépendance supplémentaire. iOS utilise MKLocalSearchCompleter, une véritable API de saisie prédictive qui répond à un fragment avec plusieurs candidats. Android utilise android.location.Geocoder, qui résout une adresse complète plutôt que de prédire à partir d’une adresse partielle : attendez-vous à environ un résultat, et à un résultat moins précis pour une rue à moitié saisie. Android ne fournit aucune saisie prédictive sans clé, et l’alternative — le SDK Places — ajouterait plusieurs mégaoctets et imposerait les autorisations de localisation à chaque application intégrant ce SDK.
  • Les défaillances de l’une ou l’autre plateforme sont silencieuses par conception : un géocodeur sans backend, sans réseau ou sans correspondance n’affiche rien et l’acheteur saisit l’adresse à la main, comme au départ. L’autocomplétion ne bloque jamais un checkout.
  • L’adresse émise utilise les mêmes clés que l’élément web et que les billing_details du jeton de confirmation, donc une seule forme de payload fonctionne sur toutes les plateformes.
  • Un élément d’adresse monté est la source de facturation du provider. Démontez-le et createConfirmationToken se rabat sur ce que vous lui transmettez directement.
Enveloppez votre application dans <WhopElements getToken={…}> une seule fois, puis montez <Payments> autour des éléments. Consultez Premiers pas et Apparence.