AddressElement

Collects a billing or shipping address. Fields, order, and validation follow the selected country. Includes street autocomplete and methods to read or validate the address.

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

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().

Mounts anywhere. Keep an AddressElementManager near your submit button to read and validate the address.

React

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>
  );
}

Example data. Open the Playground.

Props

layout · "full" | "compact"

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

line2 · "never" | "toggle" | "always"

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

name · "split" | "combined" | "none"

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

mode · "billing" | "shipping"

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

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

organization · "name" | "none" | "name_with_type"

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

defaultValues · { 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.

detectCountry · 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.

allowedCountries · string[]

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

autocomplete · 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.

customFields · ({ 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.

countryHint · 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

manager · AddressElementManager?

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

layout · AddressElement.Layout

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

scope · AddressElement.Scope

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

name · AddressElement.NameFields

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

organization · AddressElement.OrganizationFields

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

line2 · AddressElement.Line2Field

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

defaultValues · WhopAddress?

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

detectCountry · Bool

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

allowedCountries · [String]?

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

countryHint · String?

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

autocomplete · Bool

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

onChange · ((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(_:).