# Elements and Custom Checkout

This section details how to manage and interact with various Elements within the Stripe JavaScript SDK, focusing on their creation, retrieval, and event handling, particularly within the context of Custom Checkout integrations.

## Elements Overview

Elements are embeddable UI components that allow you to collect payment and other sensitive information directly within your website or application.

### Core Element Functionality

*   **Creating Elements:** The `elements.create(type: string, options?: object)` method is the primary way to instantiate new Elements. The `type` parameter specifies the kind of Element (e.g., 'expressCheckout', 'linkAuthentication', 'address', 'taxId'), and `options` can be used to configure their behavior.

    *   **Express Checkout Element:** Facilitates one-click payment acceptance.
        *   `elements.create('expressCheckout', options?: object)`
        *   Options include `allowedShippingCountries`, `applePay`, `recurringPaymentRequest`, `deferredPaymentRequest`, `automaticReloadPaymentRequest`, `billingAddressRequired`, and more.
    *   **Link Authentication Element:** Used for collecting customer authentication details.
        *   `elements.create('linkAuthentication', options?: object)`
        *   `options` can include `defaultValues` for pre-filling contact information.
    *   **Address Element:** Collects billing and shipping addresses.
        *   `elements.create('address', options?: object)`
        *   The `mode` option is required when using multiple Address Elements.
    *   **Tax ID Element:** Collects tax identification information.
        *   `elements.create('taxId')`

*   **Retrieving Elements:** If an Element has already been created, you can retrieve it using `elements.getElement(type: string, options?: object)`.

    *   `elements.getElement('payment')`
    *   `elements.getElement('expressCheckout')`
    *   `elements.getElement('linkAuthentication')`
    *   `elements.getElement('address', options?: object)` (requires `mode` if multiple are used)
    *   `elements.getElement('taxId')`

*   **Element Methods:**
    *   `element.blur()`: Blurs the Element.
    *   `element.collapse()`: Collapses a Payment Element into a row of payment method tabs.
    *   `element.getValue()`: Validates and retrieves form values from a Tax ID Element.
    *   `element.update()`: Completes when the `elements.update()` call is finished.

*   **Element Events:** Elements emit various events that you can listen to for user interactions and state changes.

    *   **`ready` event:** Triggered when the Element is fully rendered and ready for interaction. The event object may contain `availablePaymentMethods` for `expressCheckout` Elements.
    *   **`change` event:** Triggered when any value within the Element changes.
    *   **`focus` event:** Triggered when the Element gains focus.
    *   **`blur` event:** Triggered when the Element loses focus.
    *   **`escape` event:** Triggered when the escape key is pressed within an Element.
    *   **`click` event:** Triggered when the Element is clicked.
    *   **`update-end` event:** Triggered when `elements.update()` is complete.
    *   **`loaderror` event:** Triggered when an Element fails to load. This event is supported by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements. The event object includes `elementType` and an `error` object.

### Express Checkout Element Specifics

*   **`expressCheckoutElement.on('confirm', handler(event) => void)`:** Triggered when a customer finalizes their payment. The `event` object contains details like `elementType`, `expressPaymentType`, `paymentFailed`, `billingDetails`, and `shippingAddress`.
*   **`expressCheckoutElement.on('cancel', handler() => void)`:** Triggered when the payment interface is dismissed.
*   **`expressCheckoutElement.on('shippingaddresschange', handler(event) => void)`:** Triggered when a customer selects a new shipping address. Note: This event is not available for Elements with Checkout Sessions.
*   **`expressCheckoutElement.on('shippingratechange', handler(event) => void)`:** Triggered when a customer selects a new shipping rate. Note: This event is not available for Elements with Checkout Sessions.

## Custom Checkout

Custom Checkout provides a flexible way to build your checkout flow using Stripe Elements.

### Core Custom Checkout Functionality

*   **Mounting and Unmounting:**
    *   `checkout.mount(domElement: string | DOM element)`: Attaches Checkout to a specified DOM element.
    *   `checkout.unmount()`: Detaches Checkout from the DOM.
    *   `checkout.destroy()`: Removes Checkout from the DOM and destroys the instance.

*   **Actions:** The `actions` object provides methods to interact with the Checkout Session.
    *   `actions.getSession()`: Reads session data.
    *   `actions.applyPromotionCode(promotionCode: string)`: Applies a promotion code.
    *   `actions.removePromotionCode()`: Removes the currently applied promotion code.
    *   `actions.updateShippingAddress(shippingAddress: nullable object)`: Updates the customer's shipping address.
    *   `actions.updateBillingAddress(billingAddress: nullable object)`: Updates the customer's billing address.
    *   `actions.updateEmail(email: nullable string)`: Updates the customer's email address.
    *   `actions.updatePhoneNumber(phoneNumber: nullable string)`: Updates the customer's phone number.
    *   `actions.updateTaxIdInfo(taxIdInfo?: object)`: Updates the customer's business name and tax ID.
    *   `actions.updateLineItemQuantity(options: object)`: Changes the quantity of a line item.
    *   `actions.updateShippingOption(shippingOption?: string)`: Updates the selected shipping option.
    *   `actions.runServerUpdate(userFunction: function)`: Wraps an async function that updates the Checkout Session on your server.

*   **Creating Custom Checkout Elements:**
    *   `checkout.createBillingAddressElement(options?: object)`
    *   `checkout.createShippingAddressElement(options?: object)`
    *   `checkout.createCurrencySelectorElement()`
    *   `checkout.getPaymentElement()`: Retrieves the Payment Element instance.
    *   `checkout.getBillingAddressElement()`: Retrieves the Billing Address Element instance.
    *   `checkout.getShippingAddressElement()`: Retrieves the Shipping Address Element instance.
    *   `checkout.getExpressCheckoutElement()`: Retrieves the Express Checkout Element instance.
    *   `checkout.getCurrencySelectorElement()`: Retrieves the Currency Selector Element instance.

*   **Customization:**
    *   `checkout.changeAppearance(appearance: object)`: Modifies the visual customization of Elements using the Appearance API.
    *   `checkout.loadFonts(fonts: array)`: Loads additional custom fonts into Elements.

*   **Custom Checkout Element Events:** Similar to core Elements, Custom Checkout Elements also support various events:
    *   **`change` event:** Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.
    *   **`ready` event:** Triggered when the Element is fully rendered.
    *   **`focus` event:** Triggered when the Element gains focus.
    *   **`blur` event:** Triggered when the Element loses focus.
    *   **`escape` event:** Triggered when the escape key is pressed.
    *   **`loaderror` event:** Triggered when the Element fails to load.
    *   **`confirm` event:** Only available on the Express Checkout Element.
    *   **`cancel` event:** Only available on the Express Checkout Element.

*   **Checkout Events:**
    *   **`change` event:** Triggered when Checkout Session data changes (e.g., shipping address updates). The event payload is the Checkout Session object.

## React Stripe.js Checkout

This section covers the checkout functionalities provided by the `react-stripe.js` library.

### React Checkout Actions

These actions mirror the `actions` available in the standard Custom Checkout but are specific to the React environment.

*   `applyPromotionCode(promotionCode: string)`
*   `removePromotionCode()`
*   `updateShippingAddress(shippingAddress: nullable object)`
*   `updateBillingAddress(billingAddress: nullable object)`
*   `updateEmail(email: nullable string)`
*   `updatePhoneNumber(phoneNumber: nullable string)`
*   `updateTaxIdInfo(taxIdInfo?: object)`
*   `updateLineItemQuantity(options: object)`
*   `updateShippingOption(shippingOption?: string)`
*   `runServerUpdate(userFunction: function)`

## Payment Request Events

`PaymentRequest` instances emit various types of events.

## Viewport Meta Tag Requirements

To ensure a good user experience for 3D Secure, set your page's viewport `width` to `device-width` using the viewport meta tag.