Skip to main content
Esta página documenta @whop/elements@1.10.0 y @whop/elements-react@1.10.0.
Desde v1.0.0.
Se monta dentro de Payments. Pasa las props y los callbacks a través de las opciones de creación o de las props de React. Conserva el handle creado, o la ref de React, para llamar a validate() y getValues().
Uno por mode. Monta un <AddressElement /> por cada valor de mode en un mismo handle de Payments. Un segundo montaje con el mismo mode se rechaza. El mode de un elemento se establece al crearlo; para cambiarlo, destruye el elemento y crea uno nuevo.
Se monta dentro de un ámbito WhopPayments. Recopila la dirección de facturación en el formato propio del país seleccionado, y el controlador la lee para generar el token tanto si la vinculas como si no.
Móntalo dentro de <Payments>, que es dueño del cobro y del token de confirmación. <Payments> se monta a su vez dentro de <WhopElements>. Renderiza la dirección de facturación en el formato del propio país del comprador y la publica en el provider, de modo que createConfirmationToken la recoge sin que haya que pasarle nada.

Datos de ejemplo. Abre el Playground.

Props

"billing" | "shipping"
Qué dirección recopila: billing (por defecto) o shipping. También establece el propósito de autocompletado del navegador. Puedes montar uno de cada en un mismo handle. Los datos de facturación provienen del elemento de facturación o, si no hay ningún elemento de facturación montado, del elemento de envío. Por defecto es "billing".
"split" | "none" | "combined"
La fila del nombre: un campo de nombre completo (por defecto), campos separados de nombre y apellido, o ninguno. Por defecto es "combined".
"never" | "toggle" | "always"
Línea 2 de la dirección: siempre visible (por defecto), mostrada mediante un botón de texto (toggle) o nunca recopilada. Por defecto es "always".
object
Valores iniciales aplicados una vez antes del primer pintado (address.country es un código de país ISO 3166-1 alfa-2). Tienen prioridad sobre la detección del país por IP.
"full" | "compact" | "wrap"
full (por defecto) apila campos con etiqueta. compact agrupa campos etiquetados con placeholder dentro de un solo borde. wrap mantiene los campos separados de full y además coloca ciudad, estado y código postal lado a lado. Estos y los pares que full ya coloca lado a lado (nombre y apellido, organización) caben tantos por fila como permita el ancho y pasan a la siguiente línea a medida que se estrecha. Por defecto es "full".
"above" | "floating"
above (por defecto) mantiene cada etiqueta fuera de su campo: encima de él en el diseño full, como su placeholder en compact. floating usa cada etiqueta como placeholder de su campo, en cualquiera de los diseños, y luego muestra una pequeña etiqueta encima del texto escrito una vez que el campo tiene un valor. Por defecto es "above". Desde v1.5.0.
"minimal" | "full"
full (por defecto) sigue el formato de dirección completo del país seleccionado. minimal recopila solo el país y el código postal. name añade de forma independiente los campos de nombre obligatorios. Establece name en none para omitirlos. Este elemento no añade los campos que requiere un método de pago. La confirmación con tarjeta requiere un nombre, un país y un código postal, así que mantén name habilitado o pasa billingDetails.name. Por defecto es "full".
"none" | "name" | "name_with_type"
Campos de organización: ninguno (por defecto), solo el nombre, o el nombre con un selector de empresa/particular. Por defecto es "none".
boolean
Toma el país por defecto de la IP del comprador (resuelto antes del primer pintado). Si no, recurre al countryHint del controlador y luego a US. Por defecto es true.
string[]
Códigos de país ISO 3166-1 alfa-2 permitidos. Con un solo código, el selector sigue visible pero solo ofrece ese país.
boolean
Habilita las sugerencias de Google Places para la dirección de la calle. Si no aparece ninguna coincidencia o Places está bloqueado, la lista indica que no hay coincidencias y permite a los compradores introducir la dirección manualmente. En un teléfono, las sugerencias se abren a pantalla completa desde un botón de búsqueda en el campo de la calle en lugar de debajo de él, donde el teclado las taparía. Establécelo en false para un campo simple. Por defecto es true.
boolean
Muestra todos los campos de dirección desde el principio. Por defecto (false), el formulario se abre con la dirección de la calle y muestra el resto una vez que el comprador elige una sugerencia, escribe una dirección o decide introducirla manualmente. Por defecto es false. Desde v1.6.0.
object[]
Campos adicionales que se renderizan con el formulario de dirección. Los valores se validan y se emiten en el mapa custom independiente.
string
País alternativo después de defaultValues y de la detección por IP. Usa un código ISO 3166-1 alfa-2. Un valor vacío recurre a US. Por defecto es "".

Eventos

Pasa los callbacks en las opciones de creación o como props de React.

onChange

Se dispara cuando cambia la dirección. complete es true cuando todos los campos específicos del país y los campos personalizados obligatorios son válidos. address sigue los nombres de billing_details del token de confirmación, incluido postal_code. country es un código ISO 3166-1 alfa-2. Los valores personalizados están en custom.
object

onLoaderStart

Se ejecuta después de que el esqueleto de carga se pinta por primera vez y antes de onReady.

onReady

Se ejecuta después del primer pintado completo del elemento.

onError

Se ejecuta cuando el elemento no se carga o falla. El contenido de respaldo permanece visible. Usa code para el manejo programático. sourceKey identifica una fuente de estado del host que falló.
object

Métodos

Llámalos en el handle que devuelve create, o a través de una ref de React.

validate

Valida el formulario, muestra todos los errores en línea y nunca lanza excepciones. Devuelve complete, address y errors. errors está vacío exactamente cuando complete es true. Las claves usan nombres del contrato como postal_code y line1, custom:<key> para los campos personalizados, y form de forma transitoria mientras carga.Devuelve Promise<object>
boolean
requerido
object
requerido
Record<string, string>
requerido

getValues

Devuelve address y custom sin validar ni mostrar errores.Devuelve Promise<object>
object
requerido
Record<string, string>
requerido

mount

Monta el elemento en target y comienza a cargarlo. Los componentes de React se montan solos.Parámetros
string | HTMLElement
requerido

destroy

Elimina el elemento y libera su frame y sus suscripciones. Puedes llamarlo más de una vez. React elimina el elemento automáticamente.

update

Combina nuevas props en el elemento montado. En React, cambia las props del componente en su lugar.Parámetros
Partial<AddressElementProps>
requerido

Estilos

Aplica estilo a estas partes mediante appearance.classes. Usa camel case o kebab case para los nombres de las propiedades e incluye las unidades. Las hojas de estilo de la página no pueden llegar al frame del elemento. El framework valida cada declaración antes de inyectarla.
En React, pasa appearance a <Payments>. Establécelo globalmente con WhopElements({ appearance }).

Parámetros

Binding<PostalAddress>?
Lee de vuelta la dirección recopilada. El controlador la recopila en cualquier caso.
Binding<Bool>?
True una vez que todos los campos que requiere el país están rellenos y son válidos.
WhopAddressElement.Mode
.billing o .shipping. Shipping pide al teclado campos de envío. Por defecto es .billing.
WhopAddressElement.Layout
.full etiqueta todos los campos y los apila; .compact mueve las etiquetas a los placeholders. Por defecto es .full.
WhopAddressElement.Scope
.full recopila el formato completo del país; .minimal recopila solo el país y el código postal. Por defecto es .full.
WhopAddressElement.NameFields
.combined para un campo de nombre completo, .split para nombre y apellido, .none para omitir el nombre. Por defecto es .combined.
WhopAddressElement.OrganizationFields
.none, .name para el nombre de una organización, o .nameWithType para preguntar además si es una empresa o un particular. Por defecto es .none.
WhopAddressElement.Line2Field
.always muestra la segunda línea, .toggle la muestra con un botón, .never la omite. Por defecto es .toggle.
PostalAddress?
Valores de partida. Su country es un código ISO 3166-1 alfa-2 y tiene prioridad sobre la detección.
Bool
Empieza en el propio país del comprador cuando es true. Si no, recurre a countryHint, luego al país de la moneda del cobro y luego a US. Por defecto es true.
[String]?
Restringe el selector a estos códigos ISO 3166-1 alfa-2, en intersección con la restricción propia del método seleccionado.
String?
Valor alternativo ISO 3166-1 alfa-2 para la cadena de selección del país.
Bool
Sugerencias de calle mientras el comprador escribe. Si está desactivado no hay nada que elegir, así que todos los campos se muestran desde el principio. Por defecto es true.

PostalAddress

Lo que devuelve una selección:
  • country: String: ISO 3166-1 alfa-2, en mayúsculas
  • line1 / line2 / city / state / postalCode: String?, en el formato propio del país
  • name / firstName / lastName: String?, según el modo name
  • organization / organizationType: String?, según el modo organization

Estados

El formulario se renderiza inmediatamente. Con el autocompletado activado en el alcance .full, los campos de localidad aparecen después de una sugerencia o de una entrada manual; desactívalo y todos los campos se muestran a la vez. Los errores se muestran en el primer intento de confirmación y, a partir de ahí, en vivo.

Información útil

  • MapKit proporciona las sugerencias de calle en el dispositivo. Whop nunca ve la consulta del comprador mientras escribe.
  • defaultValues.country prevalece sobre la detección. La detección recurre a countryHint, luego al país de la moneda del cobro y luego a US.
  • allowedCountries se interseca con la restricción de país de facturación propia del método seleccionado, por lo que un método que solo acepta un país restringe el selector por sí solo.
  • PostalAddress usa las claves de billing_details del token de confirmación, así que el mismo JSON funciona en todas las plataformas.

Instalación

Móntalo dentro de un ámbito WhopPayments(accountID:charge:), que crea el controlador y se lo pasa a su contenido. payments.buyer es el comprador con sesión iniciada una vez que un inicio de sesión por correo electrónico lo ha verificado. WhopBrandingElement también tiene que estar en pantalla, porque Whop es el comerciante registrado en estas ventas y createConfirmationToken se rechaza sin él. Aplica estilo con .whopElementsAppearance(_:). El módulo es Elements, no WhopElements del SDK de wallet. Consulta Primeros pasos y Appearance.

Props

'billing' | 'shipping'
Propósito del autocompletado. Por defecto es billing.
'full' | 'compact'
full etiqueta todos los campos y los apila. compact mueve las etiquetas a los placeholders. Por defecto es full.
'full' | 'minimal'
full sigue el formato completo del país. minimal recopila solo el país y el código postal. Por defecto es full.
'combined' | 'split' | 'none'
Un campo de nombre completo, nombre y apellido, o ningún campo de nombre. Por defecto es combined.
'none' | 'name' | 'name_with_type'
Si se recopila una organización y si además se pregunta si es una empresa o un particular. Por defecto es none.
'toggle' | 'always' | 'never'
Cómo aparece la segunda línea de la dirección. Por defecto es toggle, que muestra un botón “Add address line 2”.
string[]
Restringe el selector de país a estos códigos ISO 3166-1 alfa-2. La propia lista de países de un método de pago seleccionado la restringe aún más, nunca la amplía.
boolean
Toma el país por defecto de la IP del comprador.
string
País alternativo después de defaultValues y de la detección por IP. ISO 3166-1 alfa-2.
{ name?: string; address?: Partial<EmittedAddress> }
Valores iniciales aplicados una vez al montar, para una sesión reanudada.
CustomFieldSpec[]
Campos adicionales renderizados en una posición declarada (after_name, after_organization, before_country, after_address). Uno obligatorio condiciona complete.
(payload: AddressChangePayload) => void
Se dispara en cada edición con la instantánea actual.
StyleProp<ViewStyle>
Se aplica al View exterior del elemento. Para la personalización del tema, es preferible appearance.parts en el provider, que cubre todos los elementos de esta superficie. Ten en cuenta que, por ahora, los nombres de las partes de React Native son un conjunto propio, no los nombres de clase whop-* de la web, por lo que un objeto de appearance de la web no se puede trasladar sin cambios.
ReactNode
Se renderiza en lugar del esqueleto integrado mientras el elemento se carga.
() => void
Se dispara una vez que el elemento es interactivo. <Payments> los agrupa, así que normalmente lo que quieres es su propio onLoadingChange.
(error: { message: string; code?: string }) => void
Un fallo de carga o de configuración de este elemento. En cualquier caso, el elemento renderiza su propia vista de error.

AddressChangePayload

Lo que devuelve onChange:
  • complete: boolean: todos los campos que requiere el país están rellenos y son válidos
  • address: EmittedAddress: lo que el comprador ha introducido hasta ahora
  • custom: Record<string, string>: valores de los customFields que hayas declarado

Estados

Un esqueleto de tres campos mientras se carga el catálogo de países y, después, el formulario. Cambiar el país vuelve a planificar los campos, porque el formato es el del país, no un conjunto fijo. onChange informa de complete cuando todos los campos que requiere el país están rellenos y son válidos.

Información útil

  • El país se toma por defecto de la IP del comprador cuando detectCountry está activado; si no, de countryHint y luego US. defaultValues.address.country anula los tres.
  • autocomplete está activado por defecto, como en la web, pero lo proporciona el geocodificador de la plataforma en lugar de Google Places, por lo que no necesita clave de API, cuenta ni dependencias adicionales. iOS usa MKLocalSearchCompleter, una API real de autocompletado mientras se escribe que responde a un fragmento con varios candidatos. Android usa android.location.Geocoder, que resuelve una dirección completa en lugar de predecir a partir de una parcial: espera aproximadamente un resultado, y uno menos preciso con una calle a medio escribir. Android no incluye autocompletado sin clave, y la alternativa (el SDK de Places) añadiría varios megabytes y obligaría a pedir permisos de ubicación en cada app que incorpore este SDK.
  • Que cualquiera de las plataformas se quede corta es silencioso por diseño: un geocodificador sin backend, sin red o sin coincidencias no muestra nada y el comprador escribe la dirección a mano, que es como empezó. El autocompletado nunca bloquea un checkout.
  • La dirección emitida usa las mismas claves que el elemento web y que billing_details del token de confirmación, así que una misma forma de payload funciona en todas las plataformas.
  • Un elemento de dirección montado es la fuente de facturación del provider. Desmóntalo y createConfirmationToken recurre a lo que le pases directamente.
Envuelve tu app en <WhopElements getToken={…}> una vez y luego monta <Payments> alrededor de los elementos. Consulta Primeros pasos y Appearance.