AddressElement - Whop Docs

This page documents @whop/elements@1.0.0-beta.3 and @whop/elements-react@1.0.0-beta.3.

Pre-release, not yet part of a stable release.

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 SwiftUI
import WhopElements

struct CheckoutScreen: View {
    @State private var manager = AddressElementManager()

    var body: some View {
        ScrollView {
            AddressElement(manager: manager) { snapshot in
                print(snapshot.isComplete)
            }
            .padding()
        }
        .safeAreaInset(edge: .bottom) {
            Button("Continue") {
                let snapshot = manager.validate()
                guard snapshot.isComplete else { return }
                print(snapshot.address.country, snapshot.address.postalCode ?? "")
            }
            .padding()
        }
    }
}

Example data. Open the Playground.

Props

"full" | "compact"

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

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

"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" | "phone" | "select" | "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

AddressElementManager?

Reads and validates the address outside the view. Keep one with @State, then call validate() before submitting.

AddressElement.Layout

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

AddressElement.Scope

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

AddressElement.NameFields

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

AddressElement.OrganizationFields

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

AddressElement.Line2Field

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

WhopAddress?

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

Bool

Uses the device region when true. Falls back to countryHint, then US. Defaults to true.

[String]?

Restrict the country picker to these ISO 3166-1 alpha-2 codes. Defaults to every country.

String?

ISO 3166-1 alpha-2 fallback for the country chain, for example one derived from the buyer’s currency.

Bool

Shows street suggestions as the buyer types. Disable it to show every field immediately. Defaults to true.

((WhopAddressSnapshot) -> Void)?

Called on every edit with the current snapshot.

`WhopAddressSnapshot`

What a selection hands back:

isComplete: Bool: every field the country requires is filled and valid
address: WhopAddress: what the buyer has entered so far
errors: [WhopAddressField: WhopAddressFieldError]: empty exactly when isComplete is true

States

The form renders immediately. manager.validate() reveals field errors and returns the current snapshot. errors is empty when isComplete is true. With autocomplete at .full scope, locality fields appear after a suggestion or manual entry. Disable autocomplete to show every field immediately.

Good to know

MapKit provides street suggestions on-device. Whop doesn’t receive the buyer’s query as they type.
defaultValues.country overrides detection. Detection falls back to countryHint, then US.
WhopAddress uses the web payload and confirmation-token billing_details keys. The same JSON works across platforms.

Call WhopSDK.configure(tokenProvider:) once at launch. Views wait for the token. See Getting started. Apply a theme with .whopTheme(_:).

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

​WhopAddressSnapshot

​States

​Good to know

​Props

​AddressChangePayload

​States

​Good to know

Props

Events

`onChange`

`onLoaderStart`

`onReady`

`onError`

Methods

`validate`

`getValues`

`mount`

`destroy`

`update`

Styling

Parameters

`WhopAddressSnapshot`

States

Good to know

Props

`AddressChangePayload`

States

Good to know