## Elements and Custom Checkout

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

### Element Creation and Retrieval

The `elements` object is your primary interface for managing Elements.

*   **Creating Elements:**
    *   `elements.create(type: string, options?: object)`: This is a general method to create an instance of an individual `Element`. You specify the `type` of Element and can provide an `options` object for configuration.
    *   `elements.create(type: 'expressCheckout', options?: object)`: Specifically for creating an Express Checkout Element. It accepts various options like `allowedShippingCountries`, `applePay`, `recurringPaymentRequest`, `deferredPaymentRequest`, and `automaticReloadPaymentRequest` for detailed configuration.
    *   `elements.create(type: 'linkAuthentication', options?: object)`: Creates a Link Authentication Element. You can provide `defaultValues` for pre-filling contact information.
    *   `checkout.createBillingAddressElement(options?: object)`: Creates a Billing Address Element within a Custom Checkout integration. It can be configured with `contacts` and `display` options for the name field.
    *   `checkout.createShippingAddressElement(options?: object)`: Creates a Shipping Address Element within a Custom Checkout integration. Similar to the billing address element, it accepts `contacts` and `display` options.
    *   `checkout.createCurrencySelectorElement()`: Creates a Currency Selector Element for Custom Checkout.
    *   `elements.create(type: string, options: object)`: Used for creating Issuing Elements.

*   **Retrieving Elements:**
    *   `elements.getElement(type: 'payment')`: Retrieves a previously created Payment Element.
    *   `elements.getElement(type: 'expressCheckout')`: Retrieves a previously created Express Checkout Element.
    *   `elements.getElement(type: 'linkAuthentication')`: Retrieves a previously created Link Authentication Element.
    *   `elements.getElement(type: 'address', options?: object)`: Retrieves an Address Element. The `mode` option is required if you have multiple Address Elements.
    *   `elements.getElement(type: 'taxId')`: Retrieves a Tax ID Element.
    *   `checkout.getPaymentElement()`: Retrieves the Payment Element instance within Custom Checkout.
    *   `checkout.getBillingAddressElement()`: Retrieves the Billing Address Element instance within Custom Checkout.
    *   `checkout.getShippingAddressElement()`: Retrieves the Shipping Address Element instance within Custom Checkout.
    *   `checkout.getExpressCheckoutElement()`: Retrieves the Express Checkout Element instance within Custom Checkout.
    *   `checkout.getCurrencySelectorElement()`: Retrieves the Currency Selector Element instance within Custom Checkout.

### Element Interactions and Events

Elements provide various methods for interaction and emit events to notify your application of changes.

*   **General Element Methods:**
    *   `element.blur()`: Blurs the Element, removing focus.
    *   `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 Events:**
    *   `element.on(event: 'update-end', handler: function)`: Triggered when `elements.update()` is complete.
    *   `element.on(event: 'change', handler: function)`: Triggered when any value in the change event payload changes. Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement` in Custom Checkout.
    *   `element.on(event: 'ready', handler: function)`: Triggered when the Element is fully rendered and ready for interaction. For `expressCheckout` Elements, it provides `availablePaymentMethods`.
    *   `element.on(event: 'focus', handler: function)`: Triggered when the Element gains focus.
    *   `element.on(event: 'blur', handler: function)`: Triggered when the Element loses focus.
    *   `element.on(event: 'escape', handler: function)`: Triggered when the escape key is pressed within an Element.
    *   `element.on(event: 'click', handler: function)`: Triggered when the Element is clicked.
    *   `element.on(event: 'loaderror', handler: function)`: Triggered when an Element fails to load. This event is emitted by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements. The event object includes `elementType` and an `error` object.

*   **Express Checkout Element Specific Events:**
    *   `expressCheckoutElement.on(event: 'confirm', handler: function)`: Triggered when the customer finalizes their payment. The handler receives an event object with details like `elementType`, `expressPaymentType`, `paymentFailed` function, `reason`, `message`, `billingDetails`, and `shippingAddress`.
    *   `expressCheckoutElement.on(event: 'cancel', handler: function)`: Triggered when the payment interface is dismissed. This can occur even after payment authorization, so ensure you handle order cancellation and refunds accordingly.
    *   `expressCheckoutElement.on(event: 'shippingaddresschange', handler: function)`: Triggered when the customer selects a new shipping address. Note: This event is not available for Elements with Checkout Sessions.
    *   `expressCheckoutElement.on(event: 'shippingratechange', handler: function)`: Triggered when the customer selects a new shipping rate. Note: This event is not available for Elements with Checkout Sessions.

### Custom Checkout Actions

Custom Checkout provides an `actions` object for manipulating the checkout session.

*   **Session Data:**
    *   `actions.getSession()`: Returns an object containing data about the Checkout Session.

*   **Promotions:**
    *   `actions.applyPromotionCode(promotionCode: string)`: Applies a promotion code to the Checkout Session.
    *   `actions.removePromotionCode()`: Removes the currently applied promotion code.

*   **Customer Information Updates:**
    *   `actions.updateShippingAddress(shippingAddress: nullable object)`: Updates the customer's shipping address. This is not used for Express Checkout payments.
    *   `actions.updateBillingAddress(billingAddress: nullable object)`: Updates the customer's billing address. This is not used for Express Checkout payments.
    *   `actions.updateEmail(email: nullable string)`: Updates the customer's email address. Crucial for Link to appear for returning users if not provided during session creation. Not used for Express Checkout payments.
    *   `actions.updatePhoneNumber(phoneNumber: nullable string)`: Updates the customer's phone number. Not used for Express Checkout payments.
    *   `actions.updateTaxIdInfo(taxIdInfo?: )`: Updates the customer's business name and tax ID.

*   **Line Items and Shipping:**
    *   `actions.updateLineItemQuantity(options: object)`: Changes the quantity of a line item.
    *   `actions.updateShippingOption(shippingOption?: string)`: Updates the selected shipping option by its ID.

*   **Server Updates:**
    *   `actions.runServerUpdate(userFunction: function)`: Wraps an async function that makes a request to your server to update the Checkout Session. It enforces a 20-second timeout.

### Custom Checkout Events

You can listen to events on the `checkout` object to respond to changes.

*   `checkout.on(event: 'change', handler: function)`: Triggered when Checkout Session data changes (e.g., shipping address update). The handler receives the updated Checkout Session object.

### Appearance and Fonts

*   `checkout.changeAppearance(appearance: object)`: Allows you to visually customize Elements using the Appearance API.
*   `checkout.loadFonts(fonts: array)`: Loads additional custom fonts into Elements.

### Embedded Checkout

For embedded Checkout integrations:

*   `checkout.mount(domElement: string | DOM element)`: Attaches Checkout to the DOM.
*   `checkout.unmount()`: Unmounts Checkout from the DOM.
*   `checkout.destroy()`: Removes and destroys the embedded Checkout instance.

### Viewport Meta Tag

For optimal 3D Secure experience, ensure your page includes the viewport meta tag with `width=device-width`.