AddressElement - Whop Docs

Mounts inside Payments. Pass props and callbacks through the create options or React props. Keep the created handle, or React ref, to call validate() and getValues().

import { WhopElements, Payments, AddressElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        <AddressElement onChange={(e) => console.log(e)} />
      </Payments>
    </WhopElements>
  );
}

import { ScrollView } from 'react-native';
import { AddressElement, Payments } from '@whop/elements-react-native';

export function BillingStep() {
  return (
    <Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
      <ScrollView>
        <AddressElement
          layout="full"
          scope="full"
          name="combined"
          line2="toggle"
          onChange={({ complete, address }) => console.log(complete, address.country)}
        />
      </ScrollView>
    </Payments>
  );
}

<script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const payments = window.WhopElements().payments.create({ /* options */ });
  payments.create('address', { onChange: (e) => console.log(e) }).mount('#payments-address');
</script>

import Elements
import SwiftUI

// .whopElements(environment:) runs once at the app root. See Getting started.
struct CheckoutScreen: View {
    @State private var address = PostalAddress()
    @State private var addressComplete = false

    var body: some View {
        WhopPayments(accountID: "biz_xxxx", charge: .plan(id: "plan_xxxx")) { payments in
            ScrollView {
                VStack(alignment: .leading, spacing: 20) {
                WhopAddressElement(address: $address, isComplete: $addressComplete)
                    WhopBrandingElement()
                }
                .padding()
            }
        }
    }
}

Example data. Open the Playground.

Props

"never" | "toggle" | "always"

Address line 2: always visible (default), revealed by a text button (toggle), or never collected. Defaults to "always".

"split" | "combined" | "none"

The name row: one full-name field (default), split first/last fields, or none. Defaults to "combined".

"full" | "compact"

full (default) stacks labeled fields. compact groups placeholder-labeled fields within one border. Defaults to "full".

"billing" | "shipping"

Browser autocomplete purpose: billing (default) or shipping. Defaults to "billing".

"full" | "minimal"

full (default) follows the selected country’s complete address format. minimal collects only country and postal code. name independently adds required name fields. Set name to none to omit them. This element does not add fields required by a payment method. Card confirmation requires a name, country, and postal code, so keep name enabled or pass billingDetails.name. Defaults to "full".

"name" | "none" | "name_with_type"

Organization fields: none (default), name only, or name with a business/individual selector. Defaults to "none".

{ name?: string | undefined; address?: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country?: string | undefined; } | undefined; }

Seed values applied once before first paint (address.country is an ISO 3166-1 alpha-2 country code). Takes precedence over IP-country detection.

boolean

Default the country from the buyer’s IP (resolved before first paint). Falls back to the controller’s countryHint, then US. Defaults to true.

string[]

Allowed ISO 3166-1 alpha-2 country codes. With one code, the selector remains visible but offers only that country.

boolean

Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. Set false for a plain input. Defaults to true.

({ key: string; label: string; type: "text" | "select" | "phone" | "date"; position: "after_name" | "after_organization" | "before_country" | "after_address"; required?: boolean | undefined; options?: string[] | undefined; format?: string | undefined; autocomplete?: string | undefined; })[]

Additional fields rendered with the address form. Values are validated and emitted in the separate custom map.

string

Fallback country after defaultValues and IP detection. Use an ISO 3166-1 alpha-2 code. An empty value falls back to US. Defaults to "".

Events

Pass callbacks in the create options or React props.

`onChange`

Fires when the address changes. complete is true when all country-specific fields and required custom fields are valid. address follows confirmation-token billing_details names, including postal_code. country is an ISO 3166-1 alpha-2 code. Custom values are in custom.Signature:

((payload: { complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }) => void)

`onLoaderStart`

Runs after the loading skeleton first paints and before onReady.Signature: (() => void)

`onReady`

Runs after the element’s first complete paint.Signature: (() => void)

`onError`

Runs when the element fails to load or crashes. The fallback remains visible. Use code for programmatic handling. sourceKey identifies a failed host-state source.Signature: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)

Methods

Call these on the handle returned by create, or through a React ref.

`validate`

Validates the form, reveals all inline errors, and never throws. Returns complete, address, and errors. errors is empty exactly when complete is true. Keys use contract names such as postal_code and line1, custom:<key> for custom fields, and transient form while loading.Signature:

() => Promise<{ complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; errors: Record<string, string>; }>

`getValues`

Returns address and custom without validation or revealing errors.Signature:

() => Promise<{ address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }>

`mount`

Mounts the element in target and starts loading. React components mount themselves.Signature: (target: string | HTMLElement) => void

`destroy`

Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.Signature: () => void

`update`

Merges new props into the mounted element. In React, change the component props instead.Signature: (options: Partial<AddressElementProps>) => void

Styling

Style these parts through appearance.classes. Use camel case or kebab case for property names and include units. Page stylesheets can’t reach the element’s frame. The framework validates each declaration before injecting it.

Class	Targets
`.whop-Address`	The address form root
`.whop-AddressErrorSummary`	The summary line shown when validation reveals missing or invalid fields
`.whop-AddressField`	One field cell in the address form
`.whop-AddressFieldError`	The error line under an address field (full layout)
`.whop-AddressFieldInput`	A text input in the address form
`.whop-AddressFieldInputInvalid`	Added to an address input while it fails validation
`.whop-AddressFieldInvalid`	Added to a compact field cell while it fails validation
`.whop-AddressFieldLabel`	Address field label in full layout
`.whop-AddressFieldSelect`	A select (country, state, organization type) in the address form
`.whop-AddressLine2Toggle`	Collapsed address line 2 toggle
`.whop-AddressManualEntry`	The “Enter address manually” text button below the collapsed form — expands the full country format
`.whop-AddressSuggestion`	One suggestion row in the autocomplete overlay
`.whop-AddressSuggestionActive`	Added to the keyboard/pointer-active suggestion row
`.whop-AddressSuggestionManual`	The “Enter address manually” row closing the suggestions list
`.whop-AddressSuggestions`	The autocomplete suggestions overlay anchored to the address line 1 field
`.whop-AddressSuggestionsEmpty`	The quiet line shown when the query settled with no address matches

const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Address': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressErrorSummary': { borderRadius: '8px', fontWeight: '600' },
      'whop-AddressField': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

// 16 classes use this shape
payments.update({
  appearance: { classes: { 'whop-Address': { fontWeight: '700' } } }
});

In React, pass appearance to <Payments>. Set it globally with WhopElements({ appearance }).

Parameters

Binding<PostalAddress>?

Reads the collected address back out. The controller collects it either way.

Binding<Bool>?

True once every field the country requires is filled and valid.

WhopAddressElement.Mode

.billing or .shipping. Shipping asks the keyboard for shipping fields. Defaults to .billing.

WhopAddressElement.Layout

.full labels every field and stacks them; .compact moves the labels into placeholders. Defaults to .full.

WhopAddressElement.Scope

.full collects the country’s whole format; .minimal collects country and postal code only. Defaults to .full.

WhopAddressElement.NameFields

.combined for one full-name field, .split for first and last, .none to leave the name out. Defaults to .combined.

WhopAddressElement.OrganizationFields

.none, .name for an organization name, or .nameWithType to also ask whether it is a business or an individual. Defaults to .none.

WhopAddressElement.Line2Field

.always shows the second line, .toggle reveals it with a button, .never leaves it out. Defaults to .toggle.

PostalAddress?

Values to start from. Its country is an ISO 3166-1 alpha-2 code and takes precedence over detection.

Bool

Starts on the buyer’s own country when true. Falls back to countryHint, then the charge currency’s country, then US. Defaults to true.

[String]?

Restricts the picker to these ISO 3166-1 alpha-2 codes, intersected with the selected method’s own constraint.

String?

ISO 3166-1 alpha-2 fallback for the country chain.

Bool

Street suggestions as the buyer types. With it off there is nothing to pick, so every field shows from the start. Defaults to true.

`PostalAddress`

What a selection hands back:

country: String: ISO 3166-1 alpha-2, uppercased
line1 / line2 / city / state / postalCode: String?, in the country’s own format
name / firstName / lastName: String?, per the name mode
organization / organizationType: String?, per the organization mode

States

The form renders immediately. With autocomplete on at .full scope, the locality fields appear after a suggestion or a manual entry; turn it off and every field shows at once. Errors reveal on the first confirm attempt, then live.

Good to know

MapKit provides the street suggestions on-device. Whop never sees the buyer’s query as they type.
defaultValues.country beats detection. Detection falls back to countryHint, then the charge currency’s country, then US.
allowedCountries is intersected with the selected method’s own billing-country constraint, so a method that only takes one country narrows the picker on its own.
PostalAddress uses the confirmation-token billing_details keys, so the same JSON works across platforms.

Install

dependencies: [
    .package(url: "https://github.com/whopio/elements-swift.git", from: "0.1.0")
]

Mount it inside a WhopPayments(accountID:charge:) scope, which creates the controller and hands it to its content. payments.buyer is the signed-in buyer once an email sign-in has proven one. WhopBrandingElement has to be on screen too, because Whop is merchant of record on these sales and createConfirmationToken refuses without it. Style with .whopElementsAppearance(_:). The module is Elements, not the wallet SDK’s WhopElements. See Getting started and Appearance.

Props

'billing' | 'shipping'

Autocomplete purpose. Defaults to billing.

'full' | 'compact'

full labels every field and stacks them. compact moves the labels into placeholders. Defaults to full.

'full' | 'minimal'

full follows the country’s complete format. minimal collects country and postal code only. Defaults to full.

'combined' | 'split' | 'none'

One full-name field, first and last, or no name field. Defaults to combined.

'none' | 'name' | 'name_with_type'

Whether to collect an organization, and whether to also ask if it is a business or an individual. Defaults to none.

'toggle' | 'always' | 'never'

How the second address line appears. Defaults to toggle, which shows an “Add address line 2” button.

string[]

Restrict the country selector to these ISO 3166-1 alpha-2 codes. A selected payment method’s own country list narrows this further, never widens it.

boolean

Default the country from the buyer’s IP.

string

Fallback country after defaultValues and IP detection. ISO 3166-1 alpha-2.

{ name?: string; address?: Partial<EmittedAddress> }

Seed values applied once at mount, for a resumed session.

CustomFieldSpec[]

Extra fields rendered at a declared position (after_name, after_organization, before_country, after_address). A required one gates complete.

(payload: AddressChangePayload) => void

Fires on every edit with the current snapshot.

StyleProp<ViewStyle>

Applied to the element’s outer View. For theming, prefer appearance.parts on the provider, which covers every element on this surface. Note the React Native part names are their own set today, not the web’s whop-* class names, so a web appearance object does not port across unchanged.

ReactNode

Rendered instead of the built-in skeleton while the element loads.

() => void

Fires once the element is interactive. <Payments> groups these, so its own onLoadingChange is usually the one you want.

(error: { message: string; code?: string }) => void

A load or configuration failure for this element. The element renders its own error face either way.

`AddressChangePayload`

What onChange hands back:

complete: boolean: every field the country requires is filled and valid
address: EmittedAddress: what the buyer has entered so far
custom: Record<string, string>: values for any customFields you declared

States

A three-field skeleton while the country catalog loads, then the form. Changing the country re-plans the fields, because the format is the country’s, not a fixed set. onChange reports complete when every field the country requires is filled and valid.

Good to know

The country defaults from the buyer’s IP when detectCountry is on, then countryHint, then US. defaultValues.address.country overrides all three.
autocomplete is on by default, as on web, but it is served by the platform geocoder rather than Google Places, so it needs no API key, no account and no extra dependency. iOS uses MKLocalSearchCompleter, a real as-you-type API that answers a fragment with several candidates. Android uses android.location.Geocoder, which resolves a complete address rather than predicting from a partial one: expect roughly one result, and a coarser one on a half-typed street. Android ships no keyless typeahead, and the alternative — the Places SDK — would add several megabytes and force location permissions on every app embedding this SDK.
Either platform falling short is silent by design: a geocoder with no backend, no network or no matches shows nothing and the buyer types the address by hand, which is where they started. Autocomplete never blocks a checkout.
The emitted address uses the same keys as the web element and the confirmation token’s billing_details, so one payload shape works across platforms.
A mounted address element is the provider’s billing source. Unmount it and createConfirmationToken falls back to whatever you pass it directly.

Wrap your app in <WhopElements getToken={…}> once, then mount <Payments> around the elements. See Getting started and Appearance.

​Props

​Events

​onChange

​onLoaderStart

​onReady

​onError

​Methods

​validate

​getValues

​mount

​destroy

​update

​Styling

​Parameters

​PostalAddress

​States

​Good to know

​Install

​Props

​AddressChangePayload

​States

​Good to know

Props

Events

`onChange`

`onLoaderStart`

`onReady`

`onError`

Methods

`validate`

`getValues`

`mount`

`destroy`

`update`

Styling

Parameters

`PostalAddress`

States

Good to know

Install

Props

`AddressChangePayload`

States

Good to know