> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.1.0` and `@whop/elements-react@1.1.0`.
*Since `v1.0.0`.*
Mounts inside [`Payments`](/elements/latest/payments/overview). Pass props and callbacks through the create options or React props. Keep the created handle, or React `ref`, to call `validate()` and `getValues()`.
**One per `mode`.** Mount one `` for each `mode` value under one Payments handle. A second mount with the same `mode` is refused. An element's `mode` is set when you create it; to change it, destroy the element and create a new one.
Mounts inside a `WhopPayments` scope. Collects the billing address in the selected country's own format, and the controller reads it for the mint whether or not you bind it.
Mount inside `
`, which owns the charge and the confirmation token. `` itself mounts inside ``. It renders the billing address in the buyer's own country format and publishes it to the provider, so `createConfirmationToken` picks it up without being passed anything.
```tsx React theme={null}
import { WhopElements, Payments, AddressElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";
function Example() {
return (
console.log(e)} />
);
}
```
```tsx React Native theme={null}
import { ScrollView } from 'react-native';
import { AddressElement, Payments } from '@whop/elements-react-native';
export function BillingStep() {
return (
console.log(complete, address.country)}
/>
);
}
```
```html JavaScript theme={null}
```
```swift Swift theme={null}
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](/elements/latest/payments/overview#playground).
## Props
Which address this collects: `billing` (default) or `shipping`. Also sets the browser autocomplete purpose. You can mount one of each under one handle. Billing details come from the billing element, or from the shipping element when no billing element is mounted. Defaults to `"billing"`.
The name row: one full-name field (default), split first/last fields, or none. Defaults to `"combined"`.
Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected. Defaults to `"always"`.
Seed values applied once before first paint (`address.country` is an ISO 3166-1 alpha-2 country code). Takes precedence over IP-country detection.
`full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border. Defaults to `"full"`.
`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 fields: none (default), name only, or name with a business/individual selector. Defaults to `"none"`.
Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US. Defaults to `true`.
Allowed ISO 3166-1 alpha-2 country codes. With one code, the selector remains visible but offers only that country.
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`.
Additional fields rendered with the address form. Values are validated and emitted in the separate `custom` map.
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
; }) => 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:` 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; }>`
### `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; }>`
### `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) => 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 |
```ts theme={null}
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 ``. Set it globally with `WhopElements({ appearance })`.
## Parameters
Reads the collected address back out. The controller collects it either way.
True once every field the country requires is filled and valid.
`.billing` or `.shipping`. Shipping asks the keyboard for shipping fields. Defaults to `.billing`.
`.full` labels every field and stacks them; `.compact` moves the labels into placeholders. Defaults to `.full`.
`.full` collects the country's whole format; `.minimal` collects country and postal code only. Defaults to `.full`.
`.combined` for one full-name field, `.split` for first and last, `.none` to leave the name out. Defaults to `.combined`.
`.none`, `.name` for an organization name, or `.nameWithType` to also ask whether it is a business or an individual. Defaults to `.none`.
`.always` shows the second line, `.toggle` reveals it with a button, `.never` leaves it out. Defaults to `.toggle`.
Values to start from. Its `country` is an ISO 3166-1 alpha-2 code and takes precedence over detection.
Starts on the buyer's own country when true. Falls back to `countryHint`, then the charge currency's country, then US. Defaults to `true`.
Restricts the picker to these ISO 3166-1 alpha-2 codes, intersected with the selected method's own constraint.
ISO 3166-1 alpha-2 fallback for the country chain.
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
```swift theme={null}
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](/elements/latest/getting-started) and [Appearance](/elements/latest/appearance).
## Props
Autocomplete purpose. Defaults to `billing`.
`full` labels every field and stacks them. `compact` moves the labels into placeholders. Defaults to `full`.
`full` follows the country's complete format. `minimal` collects country and postal code only. Defaults to `full`.
One full-name field, first and last, or no name field. Defaults to `combined`.
Whether to collect an organization, and whether to also ask if it is a business or an individual. Defaults to `none`.
How the second address line appears. Defaults to `toggle`, which shows an "Add address line 2" button.
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.
Default the country from the buyer's IP.
Fallback country after `defaultValues` and IP detection. ISO 3166-1 alpha-2.
Seed values applied once at mount, for a resumed session.
Extra fields rendered at a declared position (`after_name`, `after_organization`, `before_country`, `after_address`). A required one gates `complete`.
Fires on every edit with the current snapshot.
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.
Rendered instead of the built-in skeleton while the element loads.
Fires once the element is interactive. `` groups these, so its own `onLoadingChange` is usually the one you want.
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
`: 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 `` once, then mount `` around the elements. See [Getting started](/elements/latest/getting-started) and [Appearance](/elements/latest/appearance).