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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# AddressElement

> 청구지 또는 배송 주소를 수집합니다. 필드, 순서, 유효성 검사는 선택한 국가를 따릅니다. 거리 주소 자동 완성(휴대폰에서는 전체 화면)과 주소를 읽거나 검증하는 메서드를 포함합니다.

> [!NOTE]
>
> 이 페이지는 `@whop/elements@1.10.0` 및 `@whop/elements-react@1.10.0`을 다룹니다.

*`v1.0.0`부터 지원.*

[`Payments`](https://docs.whop.com/ko/elements/latest/payments/overview) 안에 마운트됩니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다. `validate()`와 `getValues()`를 호출하려면 생성된 핸들 또는 React `ref`를 보관하세요.

> [!NOTE]
>
> **`mode`당 하나.** 하나의 Payments 핸들 아래에서 각 `mode` 값마다 `<AddressElement />`를 하나씩 마운트하세요. 같은 `mode`로 두 번째 마운트를 시도하면 거부됩니다. 엘리먼트의 `mode`는 생성 시 설정되므로, 변경하려면 엘리먼트를 제거하고 새로 생성하세요.

`WhopPayments` 스코프 안에 마운트됩니다. 선택한 국가 고유의 형식으로 청구지 주소를 수집하며, 바인딩 여부와 관계없이 컨트롤러가 토큰 생성 시 이를 읽습니다.

청구와 확인 토큰을 소유하는 `<Payments>` 안에 마운트합니다. `<Payments>` 자체는 `<WhopElements>` 안에 마운트됩니다. 구매자 국가 고유의 형식으로 청구지 주소를 렌더링하고 프로바이더에 게시하므로, `createConfirmationToken`은 아무것도 전달받지 않아도 이를 가져옵니다.

```tsx React theme={null}
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>
  );
}
```

```tsx React Native theme={null}
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>
  );
}
```

```html JavaScript theme={null}
<script src="https://cdn.whop.com/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>
```

```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()
            }
        }
    }
}
```

예시 데이터입니다. [Playground 열기](https://docs.whop.com/ko/elements/latest/payments/overview#playground).

[React Native 예제 앱의 Android에서 실행 중인 AddressElement](https://app.revyl.ai/embed/d5ebb0fa-b4cb-48b7-8fd4-033f844518c0?controls=0)

## Props

**mode** `"billing" | "shipping"`

수집할 주소 유형으로, `billing`(기본값) 또는 `shipping`입니다. 브라우저 자동 완성 용도도 함께 설정합니다. 하나의 핸들 아래에 각각 하나씩 마운트할 수 있습니다. 청구 정보는 billing 엘리먼트에서 가져오며, billing 엘리먼트가 마운트되지 않은 경우 shipping 엘리먼트에서 가져옵니다. 기본값은 `"billing"`입니다.

**name** `"split" | "none" | "combined"`

이름 행입니다. 전체 이름 필드 하나(기본값), 이름/성 분리 필드, 또는 없음 중 하나입니다. 기본값은 `"combined"`입니다.

**line2** `"never" | "toggle" | "always"`

주소 2행입니다. 항상 표시(기본값), 텍스트 버튼으로 표시(`toggle`), 또는 수집하지 않음 중 하나입니다. 기본값은 `"always"`입니다.

**defaultValues** `object`

첫 렌더링 전에 한 번 적용되는 초기값입니다(`address.country`는 ISO 3166-1 alpha-2 국가 코드). IP 기반 국가 감지보다 우선합니다.

**속성**

**name** `string`

**address** `object`

**속성**

**name** `string`

**first\_name** `string`

**last\_name** `string`

**organization** `string`

**organization\_type** `"business" | "individual"`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string`

**layout** `"full" | "compact" | "wrap"`

`full`(기본값)은 레이블이 있는 필드를 세로로 쌓습니다. `compact`는 자리 표시자를 레이블로 사용하는 필드를 하나의 테두리 안에 그룹화합니다. `wrap`은 `full`의 개별 필드를 유지하면서 도시, 주, 우편번호를 나란히 배치합니다. 이 필드들과 `full`에서 이미 나란히 배치되는 쌍(이름과 성, 조직)은 너비가 허용하는 만큼 한 행에 배치되고, 너비가 좁아지면 줄바꿈됩니다. 기본값은 `"full"`입니다.

**labelMode** `"above" | "floating"`

`above`(기본값)는 각 레이블을 필드 밖에 둡니다. `full` 레이아웃에서는 필드 위에, `compact`에서는 자리 표시자로 표시합니다. `floating`은 두 레이아웃 모두에서 각 레이블을 필드의 자리 표시자로 사용하고, 필드에 값이 입력되면 입력된 텍스트 위에 작은 레이블을 표시합니다. 기본값은 `"above"`입니다. `v1.5.0`부터 지원.

**scope** `"minimal" | "full"`

`full`(기본값)은 선택한 국가의 전체 주소 형식을 따릅니다. `minimal`은 국가와 우편번호만 수집합니다. `name`은 이와 별개로 필수 이름 필드를 추가합니다. 생략하려면 `name`을 `none`으로 설정하세요. 이 엘리먼트는 결제 수단에 필요한 필드를 추가하지 않습니다. 카드 확인에는 이름, 국가, 우편번호가 필요하므로 `name`을 활성화된 상태로 두거나 `billingDetails.name`을 전달하세요. 기본값은 `"full"`입니다.

**organization** `"none" | "name" | "name_with_type"`

조직 필드입니다. 없음(기본값), 이름만, 또는 사업자/개인 선택기가 포함된 이름 중 하나입니다. 기본값은 `"none"`입니다.

**detectCountry** `boolean`

구매자의 IP로 기본 국가를 설정합니다(첫 렌더링 전에 결정). 실패하면 컨트롤러의 `countryHint`, 그다음 US로 대체됩니다. 기본값은 `true`입니다.

**allowedCountries** `string[]`

허용되는 ISO 3166-1 alpha-2 국가 코드입니다. 코드가 하나이면 선택기는 계속 표시되지만 해당 국가만 제공합니다.

**autocomplete** `boolean`

거리 주소에 Google Places 제안을 활성화합니다. 일치하는 항목이 없거나 Places가 차단된 경우 목록에 일치 항목이 없다고 표시하고 구매자가 주소를 직접 입력할 수 있게 합니다. 휴대폰에서는 키보드가 가리지 않도록 제안이 거리 필드 아래가 아니라 거리 필드의 검색 버튼에서 전체 화면으로 열립니다. 일반 입력을 사용하려면 `false`로 설정하세요. 기본값은 `true`입니다.

**expanded** `boolean`

처음부터 모든 주소 필드를 표시합니다. 기본적으로(`false`) 양식은 거리 주소로 시작하며, 구매자가 제안을 선택하거나 주소를 입력하거나 직접 입력을 선택하면 나머지 필드를 표시합니다. 기본값은 `false`입니다. `v1.6.0`부터 지원.

**customFields** `object[]`

주소 양식과 함께 렌더링되는 추가 필드입니다. 값은 유효성 검사를 거쳐 별도의 `custom` 맵으로 전달됩니다.

**속성**

**key** `string` *required*

**label** `string` *required*

**type** `"phone" | "text" | "select" | "date"` *required*

**position** `string` *required*

`"after_name"`, `"after_organization"`, `"before_country"`, `"after_address"` 중 하나입니다.

**required** `boolean`

**options** `string[]`

**format** `string`

**autocomplete** `string`

**countryHint** `string`

`defaultValues`와 IP 감지 이후의 대체 국가입니다. ISO 3166-1 alpha-2 코드를 사용하세요. 빈 값이면 `US`로 대체됩니다. 기본값은 `""`입니다.

## 이벤트

생성 옵션 또는 React props로 콜백을 전달합니다.

### `onChange`

주소가 변경될 때 실행됩니다. 국가별 필드와 필수 사용자 지정 필드가 모두 유효하면 `complete`가 true입니다. `address`는 `postal_code`를 포함해 확인 토큰의 `billing_details` 이름을 따릅니다. `country`는 ISO 3166-1 alpha-2 코드입니다. 사용자 지정 값은 `custom`에 있습니다.

**payload** `object`

**속성**

**complete** `boolean` *required*

**address** `object` *required*

**속성**

**name** `string`

**first\_name** `string`

**last\_name** `string`

**organization** `string`

**organization\_type** `"business" | "individual"`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string` *required*

**custom** `Record\<string, string\>` *required*

### `onLoaderStart`

로딩 스켈레톤이 처음 그려진 후, `onReady` 전에 실행됩니다.

### `onReady`

엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.

### `onError`

엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 `code`를 사용하세요. `sourceKey`는 실패한 호스트 상태 소스를 식별합니다.

**e** `object`

**속성**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

`create`가 반환한 핸들에서, 또는 React `ref`를 통해 호출합니다.

### `validate`

양식의 유효성을 검사하고 모든 인라인 오류를 표시하며, 예외를 발생시키지 않습니다. `complete`, `address`, `errors`를 반환합니다. `errors`는 `complete`가 true일 때만 정확히 비어 있습니다. 키는 `postal_code`, `line1` 같은 계약 이름을 사용하고, 사용자 지정 필드에는 `custom:<key>`, 로딩 중에는 일시적으로 `form`을 사용합니다.

**반환값** `Promise<object>`

**complete** `boolean` *required*

**address** `object` *required*

**속성**

**name** `string`

**first\_name** `string`

**last\_name** `string`

**organization** `string`

**organization\_type** `"business" | "individual"`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string` *required*

**errors** `Record\<string, string\>` *required*

### `getValues`

유효성 검사나 오류 표시 없이 `address`와 `custom`을 반환합니다.

**반환값** `Promise<object>`

**address** `object` *required*

**속성**

**name** `string`

**first\_name** `string`

**last\_name** `string`

**organization** `string`

**organization\_type** `"business" | "individual"`

**line1** `string`

**line2** `string`

**city** `string`

**state** `string`

**postal\_code** `string`

**country** `string` *required*

**custom** `Record\<string, string\>` *required*

### `mount`

`target`에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.

**매개변수**

**target** `string | HTMLElement` *required*

### `destroy`

엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.

### `update`

마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.

**매개변수**

**options** `Partial\<AddressElementProps\>` *required*

## 스타일링

`appearance.classes`를 통해 다음 부분의 스타일을 지정합니다. 속성 이름은 카멜 케이스 또는 케밥 케이스를 사용하고 단위를 포함하세요. 페이지 스타일시트는 엘리먼트의 프레임에 적용되지 않습니다. 프레임워크는 각 선언을 삽입하기 전에 유효성을 검사합니다.

| 클래스 | 대상 |
| - | - |
| `.whop-Address` | 주소 양식 루트 |
| `.whop-AddressErrorSummary` | 유효성 검사에서 누락되거나 잘못된 필드가 드러날 때 표시되는 요약 줄 |
| `.whop-AddressField` | 주소 양식의 필드 셀 하나 |
| `.whop-AddressFieldError` | 주소 필드의 오류 줄: 전체 레이아웃에서는 필드 아래, 컴팩트 레이아웃에서는 작성기 메시지용으로 그룹 아래에 표시 |
| `.whop-AddressFieldInput` | 주소 양식의 텍스트 입력 |
| `.whop-AddressFieldInputInvalid` | 주소 입력이 유효성 검사에 실패하는 동안 추가됨 |
| `.whop-AddressFieldInvalid` | 컴팩트 필드 셀이 유효성 검사에 실패하는 동안 추가됨 |
| `.whop-AddressFieldLabel` | 주소 필드 레이블: 필드 위, 또는 플로팅 레이블 사용 시 필드 안 |
| `.whop-AddressFieldSelect` | 주소 양식의 선택 항목(국가, 주, 조직 유형) |
| `.whop-AddressGroup` | 컴팩트 레이아웃에서 모든 필드를 담는 테두리 그룹 |
| `.whop-AddressLine2Toggle` | 접힌 주소 2행 토글 |
| `.whop-AddressManualEntry` | 접힌 양식 아래의 "Enter address manually" 텍스트 버튼 — 국가별 전체 형식을 펼침 |
| `.whop-AddressSearchButton` | 휴대폰에서 거리 필드 끝에 있는 검색 버튼 |
| `.whop-AddressSuggestion` | 자동 완성 오버레이의 제안 행 하나 |
| `.whop-AddressSuggestionActive` | 키보드/포인터로 활성화된 제안 행에 추가됨 |
| `.whop-AddressSuggestionManual` | 제안 목록을 마무리하는 "Enter address manually" 행 |
| `.whop-AddressSuggestions` | 주소 1행 필드에 고정된 자동 완성 제안 오버레이 |
| `.whop-AddressSuggestionsEmpty` | 검색어 입력이 끝났지만 일치하는 주소가 없을 때 표시되는 조용한 안내 줄 |

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

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

React에서는 `appearance`를 `<Payments>`에 전달합니다. 전역으로 설정하려면 `WhopElements({ appearance })`를 사용하세요.

## 매개변수

**address** `Binding\<PostalAddress\>?`

수집된 주소를 다시 읽어옵니다. 어떤 경우든 컨트롤러가 주소를 수집합니다.

**isComplete** `Binding\<Bool\>?`

국가에서 요구하는 모든 필드가 채워지고 유효하면 true입니다.

**mode** `WhopAddressElement.Mode`

`.billing` 또는 `.shipping`입니다. shipping은 키보드에 배송 필드용 입력을 요청합니다. 기본값은 `.billing`입니다.

**layout** `WhopAddressElement.Layout`

`.full`은 모든 필드에 레이블을 붙여 세로로 쌓고, `.compact`는 레이블을 자리 표시자로 옮깁니다. 기본값은 `.full`입니다.

**scope** `WhopAddressElement.Scope`

`.full`은 국가의 전체 형식을 수집하고, `.minimal`은 국가와 우편번호만 수집합니다. 기본값은 `.full`입니다.

**name** `WhopAddressElement.NameFields`

전체 이름 필드 하나는 `.combined`, 이름과 성 분리는 `.split`, 이름 생략은 `.none`입니다. 기본값은 `.combined`입니다.

**organization** `WhopAddressElement.OrganizationFields`

`.none`, 조직 이름은 `.name`, 사업자인지 개인인지도 묻으려면 `.nameWithType`입니다. 기본값은 `.none`입니다.

**line2** `WhopAddressElement.Line2Field`

`.always`는 두 번째 행을 표시하고, `.toggle`은 버튼으로 표시하며, `.never`는 생략합니다. 기본값은 `.toggle`입니다.

**defaultValues** `PostalAddress?`

시작 값입니다. `country`는 ISO 3166-1 alpha-2 코드이며 감지보다 우선합니다.

**detectCountry** `Bool`

true이면 구매자 자신의 국가로 시작합니다. 실패하면 `countryHint`, 그다음 청구 통화의 국가, 그다음 US로 대체됩니다. 기본값은 `true`입니다.

**allowedCountries** `[String]?`

선택기를 이 ISO 3166-1 alpha-2 코드로 제한하며, 선택된 결제 수단 자체의 제약과 교집합을 적용합니다.

**countryHint** `String?`

국가 결정 순서의 ISO 3166-1 alpha-2 대체값입니다.

**autocomplete** `Bool`

구매자가 입력할 때 거리 제안을 표시합니다. 끄면 선택할 항목이 없으므로 처음부터 모든 필드가 표시됩니다. 기본값은 `true`입니다.

## `PostalAddress`

선택 시 반환되는 값:

* `country: String`: 대문자 ISO 3166-1 alpha-2
* `line1` / `line2` / `city` / `state` / `postalCode`: `String?`, 국가 고유의 형식
* `name` / `firstName` / `lastName`: `String?`, `name` 모드에 따름
* `organization` / `organizationType`: `String?`, `organization` 모드에 따름

## 상태

양식은 즉시 렌더링됩니다. `.full` 범위에서 자동 완성이 켜져 있으면 지역 필드는 제안을 선택하거나 직접 입력한 후에 나타나며, 끄면 모든 필드가 한 번에 표시됩니다. 오류는 첫 번째 확인 시도 시 표시되고, 이후에는 실시간으로 표시됩니다.

## 알아두면 좋은 점

* MapKit이 기기에서 거리 제안을 제공합니다. Whop은 구매자가 입력하는 검색어를 절대 보지 않습니다.
* `defaultValues.country`가 감지보다 우선합니다. 감지에 실패하면 `countryHint`, 그다음 청구 통화의 국가, 그다음 US로 대체됩니다.
* `allowedCountries`는 선택된 결제 수단 자체의 청구 국가 제약과 교집합이 적용되므로, 한 국가만 허용하는 결제 수단은 자체적으로 선택기를 좁힙니다.
* `PostalAddress`는 확인 토큰의 `billing_details` 키를 사용하므로 같은 JSON이 여러 플랫폼에서 작동합니다.

## 설치

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/whopio/elements-swift.git", from: "0.1.0")
]
```

> [!NOTE]
>
> 컨트롤러를 생성하여 콘텐츠에 전달하는 `WhopPayments(accountID:charge:)` 스코프 안에 마운트하세요. 이메일 로그인으로 구매자가 확인되면 `payments.buyer`는 로그인한 구매자입니다. Whop은 이러한 판매의 판매 대행자이며 `createConfirmationToken`은 `WhopBrandingElement` 없이는 거부되므로, 이 엘리먼트도 화면에 있어야 합니다. 스타일은 `.whopElementsAppearance(_:)`로 지정합니다. 모듈은 지갑 SDK의 `WhopElements`가 아니라 `Elements`입니다. [시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md) 및 [Appearance](https://docs.whop.com/ko/elements/latest/appearance.md)를 참고하세요.

## Props

**mode** `'billing' | 'shipping'`

자동 완성 용도입니다. 기본값은 `billing`입니다.

**layout** `'full' | 'compact'`

`full`은 모든 필드에 레이블을 붙여 세로로 쌓습니다. `compact`는 레이블을 자리 표시자로 옮깁니다. 기본값은 `full`입니다.

**scope** `'full' | 'minimal'`

`full`은 국가의 전체 형식을 따릅니다. `minimal`은 국가와 우편번호만 수집합니다. 기본값은 `full`입니다.

**name** `'combined' | 'split' | 'none'`

전체 이름 필드 하나, 이름과 성, 또는 이름 필드 없음입니다. 기본값은 `combined`입니다.

**organization** `'none' | 'name' | 'name_with_type'`

조직을 수집할지 여부와 사업자인지 개인인지도 물을지 여부입니다. 기본값은 `none`입니다.

**line2** `'toggle' | 'always' | 'never'`

두 번째 주소 행이 표시되는 방식입니다. 기본값은 `toggle`이며, "Add address line 2" 버튼을 표시합니다.

**allowedCountries** `string[]`

국가 선택기를 이 ISO 3166-1 alpha-2 코드로 제한합니다. 선택된 결제 수단 자체의 국가 목록은 이를 더 좁힐 뿐 넓히지 않습니다.

**detectCountry** `boolean`

구매자의 IP로 기본 국가를 설정합니다.

**countryHint** `string`

`defaultValues`와 IP 감지 이후의 대체 국가입니다. ISO 3166-1 alpha-2.

**defaultValues** `\{ name?: string; address?: Partial\<EmittedAddress\> \}`

재개된 세션을 위해 마운트 시 한 번 적용되는 초기값입니다.

**customFields** `CustomFieldSpec[]`

선언된 위치(`after_name`, `after_organization`, `before_country`, `after_address`)에 렌더링되는 추가 필드입니다. 필수 필드는 `complete`의 조건이 됩니다.

**onChange** `(payload: AddressChangePayload) =\> void`

편집할 때마다 현재 스냅샷과 함께 실행됩니다.

**style** `StyleProp\<ViewStyle\>`

엘리먼트의 외부 `View`에 적용됩니다. 테마 지정에는 이 화면의 모든 엘리먼트에 적용되는 프로바이더의 `appearance.parts`를 사용하는 것이 좋습니다. 현재 React Native 파트 이름은 웹의 `whop-*` 클래스 이름과 별개의 체계이므로, 웹 appearance 객체를 그대로 옮겨 쓸 수 없습니다.

**fallback** `ReactNode`

엘리먼트가 로드되는 동안 기본 스켈레톤 대신 렌더링됩니다.

**onReady** `() =\> void`

엘리먼트가 상호작용 가능해지면 한 번 실행됩니다. `<Payments>`가 이를 그룹화하므로 보통은 `<Payments>` 자체의 `onLoadingChange`를 사용하는 것이 좋습니다.

**onError** `(error: \{ message: string; code?: string \}) =\> void`

이 엘리먼트의 로드 또는 구성 실패입니다. 어떤 경우든 엘리먼트는 자체 오류 화면을 렌더링합니다.

## `AddressChangePayload`

`onChange`가 반환하는 값:

* `complete: boolean`: 국가에서 요구하는 모든 필드가 채워지고 유효함
* `address: EmittedAddress`: 구매자가 지금까지 입력한 내용
* `custom: Record<string, string>`: 선언한 `customFields`의 값

## 상태

국가 카탈로그가 로드되는 동안 세 필드 스켈레톤이 표시된 후 양식이 표시됩니다. 형식은 고정된 세트가 아니라 국가별이므로 국가를 변경하면 필드가 다시 구성됩니다. 국가에서 요구하는 모든 필드가 채워지고 유효하면 `onChange`가 `complete`를 보고합니다.

## 알아두면 좋은 점

* `detectCountry`가 켜져 있으면 국가는 구매자의 IP, 그다음 `countryHint`, 그다음 US 순으로 기본 설정됩니다. `defaultValues.address.country`는 이 세 가지보다 모두 우선합니다.
* `autocomplete`는 웹과 마찬가지로 기본적으로 켜져 있지만, Google Places가 아닌 **플랫폼 지오코더**가 제공하므로 API 키, 계정, 추가 종속성이 필요하지 않습니다. iOS는 입력 중인 일부 문자열에 여러 후보로 응답하는 실시간 입력 API인 `MKLocalSearchCompleter`를 사용합니다. Android는 부분 입력에서 예측하는 대신 *완전한* 주소를 해석하는 `android.location.Geocoder`를 사용합니다. 대략 하나의 결과가 나오며, 거리를 절반만 입력한 경우 더 대략적인 결과가 나옵니다. Android에는 키가 필요 없는 자동 완성 기능이 없으며, 대안인 Places SDK는 수 메가바이트를 추가하고 이 SDK를 삽입하는 모든 앱에 위치 권한을 강제합니다.
* 어느 플랫폼이든 기능이 부족할 때는 의도적으로 조용히 처리됩니다. 백엔드나 네트워크가 없거나 일치 항목이 없는 지오코더는 아무것도 표시하지 않으며, 구매자는 처음처럼 주소를 직접 입력합니다. 자동 완성은 절대 체크아웃을 막지 않습니다.
* 전달되는 주소는 웹 엘리먼트 및 확인 토큰의 `billing_details`와 같은 키를 사용하므로 하나의 페이로드 형태가 여러 플랫폼에서 작동합니다.
* 마운트된 주소 엘리먼트는 프로바이더의 청구 정보 소스입니다. 언마운트하면 `createConfirmationToken`은 직접 전달한 값으로 대체됩니다.

> [!NOTE]
>
> 앱을 `<WhopElements getToken={…}>`로 한 번 감싼 다음, 엘리먼트를 `<Payments>`로 감싸 마운트하세요. [시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md) 및 [Appearance](https://docs.whop.com/ko/elements/latest/appearance.md)를 참고하세요.


## Related topics

- [PaymentElement](https://docs.whop.com/ko/elements/latest/payments/payment.md)
- [Elements 시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md)
- [BrandingElement](https://docs.whop.com/ko/elements/latest/payments/branding.md)
