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

# EmailElement

> 구매자의 이메일을 수집하고, 마운트되어 있는 동안 `payments.createConfirmationToken()`에 전달합니다. 명시적으로 지정한 `billingDetails.email`이 우선합니다. 일치하는 Whop 계정이 있으면 코드 인증 또는 계정에 패스키가 있는 경우 패스키를 사용한 선택적 로그인이 표시됩니다. 로그인에 성공하면 payment 엘리먼트에서 저장된 결제 수단을 사용할 수 있습니다. 구매자는 게스트로 계속 진행할 수 있습니다.

> [!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로 전달합니다.

`WhopPayments` 스코프 안에 마운트됩니다. 모든 확인 토큰에 필요한 구매자의 이메일을 수집하며, 바인딩 여부와 관계없이 컨트롤러가 토큰 발급 시 이 값을 읽습니다.

결제 금액과 확인 토큰을 소유하는 `<Payments>` 안에 마운트하세요. `<Payments>` 자체는 `<WhopElements>` 안에 마운트됩니다. 구매자의 이메일을 수집하여 프로바이더에 게시하므로, 아무것도 전달하지 않아도 `createConfirmationToken`이 이메일을 전송합니다.

```tsx React theme={null}
import { WhopElements, Payments, EmailElement } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

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

```tsx React Native theme={null}
import { EmailElement, Payments } from '@whop/elements-react-native';

export function ContactStep() {
  return (
    <Payments accountId="biz_xxxxxxxx" plan="plan_xxxxxxxx">
      <EmailElement onChange={({ email, complete }) => console.log(email, complete)} />
    </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('email', { onChange: (e) => console.log(e) }).mount('#payments-email');
</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 email = ""

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

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

[React Native 예제 앱의 Android에서 실행 중인 EmailElement](https://app.revyl.ai/embed/00ebe239-4c8b-4fe4-90d9-0e57771e2f35?controls=0)

## Props

**label** `boolean`

현지화된 레이블을 표시합니다. 직접 레이블을 제공하는 경우 `false`로 설정하세요. 입력란에는 현지화된 `aria-label`이 유지됩니다. 기본값은 `true`입니다.

**placeholder** `string`

이메일 입력란의 플레이스홀더 텍스트입니다. 비어 있으면(기본값) `you@example.com`이 렌더링됩니다. 플로팅 레이블을 사용하면 레이블 텍스트가 대신 플레이스홀더가 됩니다. 기본값은 `""`입니다.

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

`above`(기본값)는 입력란 위에 레이블을 표시합니다. `floating`은 레이블 텍스트를 플레이스홀더로 사용하다가, 입력란에 값이 들어가면 입력한 텍스트 위에 작은 레이블을 표시합니다. `label`이 `false`이면 무시됩니다. 기본값은 `"above"`입니다. `v1.5.0`부터 지원.

**defaultValue** `string`

마운트 시 한 번 적용되는 초기값입니다. 기본값은 `""`입니다.

## 이벤트

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

### `onChange`

이메일이 변경될 때 실행됩니다. 유효해 보이는 값이면 `complete`가 true입니다. 로그인 시에는 로그인한 이메일과 함께 실행되며, 이 이메일은 `createConfirmationToken()`에도 사용됩니다.

**payload** `object`

**속성**

**email** `string` *required*

**complete** `boolean` *required*

### `onLoaderStart`

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

### `onReady`

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

### `onError`

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

**e** `object`

**속성**

**message** `string` *required*

**code** `string`

**sourceKey** `string`

## 메서드

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

### `mount`

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

**매개변수**

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

### `destroy`

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

### `update`

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

**매개변수**

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

## 스타일링

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

| 클래스 | 대상 |
| - | - |
| `.whop-Email` | 이메일 엘리먼트 루트 |
| `.whop-EmailChecking` | 이메일을 확인하거나 로그인 코드를 보내는 동안 표시되는 진행 윤곽선 |
| `.whop-EmailCodeHint` | 로그인 코드를 요청하는 줄 |
| `.whop-EmailError` | 유효하지 않은 이메일 메시지 |
| `.whop-EmailInput` | 이메일 입력란 |
| `.whop-EmailInputInvalid` | 유효하지 않아 보이는 값이 입력된 이메일 입력란 |
| `.whop-EmailLabel` | 이메일 필드 레이블 |
| `.whop-EmailPasskey` | 이메일 입력란 안의 패스키 로그인 버튼 |
| `.whop-EmailSignedIn` | 로그인한 구매자 행 |
| `.whop-EmailSignIn` | 다시 오신 것을 환영하는 로그인 컨트롤 |
| `.whop-EmailSignInError` | 로그인 오류 메시지 |
| `.whop-EmailSignOut` | 다른 이메일 선택 컨트롤 |
| `.whop-EmailWelcome` | 계정 이메일 위에 표시되는 환영 화면 인사말 |
| `.whop-VerificationError` | 대화 상자의 실패 메시지 |
| `.whop-VerificationInput` | 일회용 코드 입력란 |
| `.whop-VerificationInputInvalid` | 시도가 실패한 후 코드 입력란에 추가됨 |
| `.whop-VerificationInputSlot` | 일회용 코드 입력란의 숫자 한 칸 |
| `.whop-VerificationInputSlotActive` | 구매자가 입력 중인 코드 칸에 추가됨 |
| `.whop-VerificationPending` | 제출이 진행되는 동안 표시되는 인증 중… 줄 |

```ts theme={null}
const payments = whop.payments.create({
  appearance: {
    classes: {
      'whop-Email': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailChecking': { borderRadius: '8px', fontWeight: '600' },
      'whop-EmailCodeHint': { borderRadius: '8px', fontWeight: '600' }
    }
  }
});

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

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

## 매개변수

**email** `Binding\<String\>?`

값을 다시 읽어옵니다. 컨트롤러는 어느 경우든 값을 수집합니다.

**showsLabel** `Bool`

직접 레이블을 제공하는 경우 false로 설정하세요. 입력란에는 접근성 레이블이 유지됩니다. 기본값은 `true`입니다.

**placeholder** `String?`

비어 있으면 `you@example.com`이 렌더링됩니다.

## 상태

즉시 렌더링됩니다. 유효하지 않아 보이는 주소는 필드에서 포커스가 벗어나면 오류를 표시하고, 이후에는 실시간으로 표시합니다.

## 알아두면 좋은 점

* 이 엘리먼트가 없으면 `createConfirmationToken`에 `billingDetails.email`을 직접 전달하세요. 이메일이 없는 토큰은 발급이 거부됩니다.
* 토큰 발급 시 명시적으로 지정한 `billingDetails.email`이 이 엘리먼트가 수집한 값보다 우선합니다.
* 유효해 보이는 주소는 디바운스를 거쳐, 그리고 포커스를 벗어날 때 다시 계정 디렉터리에서 조회됩니다. 인식된 주소에는 로그인이 제안되며, 엘리먼트가 여섯 자리 코드 시트를 직접 표시합니다.
* 인증된 로그인은 [`WhopPaymentElement`](https://docs.whop.com/ko/elements/latest/payments/payment#swift)에서 구매자의 저장된 결제 수단을 사용할 수 있게 합니다. 구매자가 누구인지는 `payments.buyer`로 확인하고, 구매자 정보를 지우려면 `payments.signOut()`을 사용하세요.
* 범위가 지정된 토큰은 한 시간 동안 유지되며 갱신되지 않습니다. 만료되면 저장된 결제 경로가 비어 있는 상태로 돌아오며, 구매자는 게스트와 동일한 경로로 새 결제 수단을 사용해 결제합니다.

## 설치

```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

**defaultValue** `string`

마운트 시 한 번 적용되는 초기값입니다.

**label** `boolean`

현지화된 레이블을 표시합니다. 기본값은 `true`입니다.

**placeholder** `string`

비어 있으면 `you@example.com`이 렌더링됩니다.

**onChange** `(payload: EmailChangePayload) =\> 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`

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

## `EmailChangePayload`

`onChange`가 반환하는 값:

* `email: string`: 현재 값
* `complete: boolean`: 주소가 올바르게 파싱됨

## 상태

즉시 렌더링됩니다. 주소가 올바르게 파싱되면 `onChange`가 `complete`를 보고하며, 엘리먼트는 포커스가 벗어날 때 자체 유효성 검사 메시지를 표시합니다.

## 알아두면 좋은 점

* 게시된 이메일은 확인 토큰에 `billing_details.email`로 포함됩니다. `createConfirmationToken`에 `billingDetails.email`을 전달하면 이 값을 재정의합니다.
* 폼에서 직접 레이블을 제공하는 경우 `label={false}`로 설정하세요. 어느 경우든 입력란에는 접근성 레이블이 유지됩니다.

> [!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

- [Elements 시작하기](https://docs.whop.com/ko/elements/latest/getting-started.md)
- [BrandingElement](https://docs.whop.com/ko/elements/latest/payments/branding.md)
- [Payment Elements로 체크아웃 구축하기](https://docs.whop.com/ko/developer/guides/payment-elements.md)
