## Elements and Elements-related Components

This section details various JavaScript Elements and related components for building payment and checkout experiences. It covers creating, retrieving, and interacting with different types of Elements, as well as handling events and managing checkout sessions.

### Core Element Management

*   **Creating Elements:**
    *   `elements.create(type: string, options?: object)`: Creates an instance of an individual `Element`.
    *   `elements.create(type: 'expressCheckout', options?: object)`: Creates an instance of the Express Checkout Element.
    *   `elements.create(type: 'linkAuthentication', options?: object)`: Creates an instance of the Link Authentication Element.
*   **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 a previously created Address Element.
    *   `elements.getElement(type: 'taxId')`: Retrieves a previously created Tax ID Element.

### Specific Element Types

*   **Express Checkout Element:**
    *   Provides an embeddable component for accepting payments through one-click payment buttons.
    *   **Events:**
        *   `expressCheckoutElement.on(event: 'confirm', handler: function)`: Triggered when the customer finalizes their payment.
        *   `expressCheckoutElement.on(event: 'cancel', handler: function)`: Triggered when the payment interface is dismissed.
        *   `expressCheckoutElement.on(event: 'shippingaddresschange', handler: function)`: Triggered when the customer selects a new shipping address.
        *   `expressCheckoutElement.on(event: 'shippingratechange', handler: function)`: Triggered when the customer selects a new shipping rate.
*   **Link Authentication Element:**
    *   Used for creating a Link Authentication Element instance.
*   **Address Element:**
    *   An embeddable component for collecting local and international billing and shipping addresses.
*   **Tax ID Element:**
    *   Used for retrieving a Tax ID Element.
    *   `element.getValue()`: Validates and retrieves form values from a Tax ID Element.

### Element Methods and Events

*   **Element Instance Methods:**
    *   `element.collapse()`: Collapses the Payment Element into a row of payment method tabs.
    *   `element.blur()`: Blurs the [Element](https://docs.stripe.com/js/element.md).
*   **Common Element Events:**
    *   `element.on(event: 'update-end', handler: function)`: Triggered when the call to `elements.update()` is complete.
    *   `element.on(event: 'change', handler: function)`: Triggered when any value in the change event payload changes.
    *   `element.on(event: 'ready', handler: function)`: Triggered when the `Element` is fully rendered.
    *   `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)`: Handles click events on an Element.
    *   `element.on(event: 'loaderror', handler: function)`: Triggered when the `Element` fails to load.

### Custom Checkout

*   **Mounting and Unmounting:**
    *   `checkout.mount(domElement: string | DOM element)`: Attaches Checkout to the DOM.
    *   `checkout.unmount()`: Unmounts Checkout from the DOM.
    *   `checkout.destroy()`: Removes Checkout from the DOM and destroys it.
*   **Session Data and Actions:**
    *   `actions.getSession()`: Returns an object that contains data about the Checkout Session.
    *   `actions.applyPromotionCode(promotionCode: string)`: Applies a promotion code to the Checkout Session.
    *   `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?: )`: 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 makes a request to your server to update the Checkout Session.
*   **Creating Custom Checkout Elements:**
    *   `checkout.createBillingAddressElement(options?: object)`: Creates an instance of a Billing Address Element.
    *   `checkout.createShippingAddressElement(options?: object)`: Creates an instance of a Shipping Address Element.
    *   `checkout.createCurrencySelectorElement()`: Creates an instance of a Currency Selector Element.
*   **Retrieving Custom Checkout Elements:**
    *   `checkout.getPaymentElement()`: Gets the previously created Payment Element instance.
    *   `checkout.getBillingAddressElement()`: Gets the previously created Billing Address Element instance.
    *   `checkout.getShippingAddressElement()`: Gets the previously created Shipping Address Element instance.
    *   `checkout.getExpressCheckoutElement()`: Gets the previously created Express Checkout Element instance.
    *   `checkout.getCurrencySelectorElement()`: Gets the previously created Currency Selector Element instance.
*   **Customization:**
    *   `checkout.changeAppearance(appearance: object)`: Changes the visual customization of Elements using the Appearance API.
    *   `checkout.loadFonts(fonts: array)`: Loads additional custom fonts into Elements.
*   **Custom Checkout Element Events:**
    *   `element.on(event: 'change', handler: function)`: Triggered when any value in the change event payload changes for supported elements.
    *   `element.on(event: 'ready', handler: function)`: Triggered when the `Element` is fully rendered.
    *   `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: 'loaderror', handler: function)`: Triggered when the `Element` fails to load.
    *   `expressCheckoutElement.on(event: 'confirm', handler: function)`: Triggered from the Express Checkout Element when the customer finalizes their payment.
    *   `expressCheckoutElement.on(event: 'cancel', handler: function)`: Triggered from the Express Checkout Element when the payment interface is dismissed.
*   **Checkout Events:**
    *   `checkout.on(event: 'change', handler: function)`: Triggered when Checkout Session data changes.

### React Stripe.js Checkout

*   **Checkout Actions:**
    *   `applyPromotionCode(promotionCode: string)`: Applies a promotion code.
    *   `removePromotionCode()`: Removes the currently applied promotion code.
    *   `updateShippingAddress(shippingAddress: nullable object)`: Updates the Customer's shipping address.
    *   `updateBillingAddress(billingAddress: nullable object)`: Updates the Customer's billing address.
    *   `updateEmail(email: nullable string)`: Updates the Customer's email address.
    *   `updatePhoneNumber(phoneNumber: nullable string)`: Updates the Customer's phone number.
    *   `updateTaxIdInfo(taxIdInfo?: )`: Updates the Customer's business name and tax ID.
    *   `updateLineItemQuantity(options: object)`: Changes the quantity of a line item.
    *   `updateShippingOption(shippingOption?: string)`: Updates the selected shipping option.
    *   `runServerUpdate(userFunction: function)`: Wraps an async function to update the Checkout Session.

### Payment Request Events

*   `PaymentRequest` instances emit various types of events.

### Viewport Meta Tag Requirements

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