## Elements

This section details the various Elements available for use with Stripe.js, covering their creation, retrieval, and event handling.

### Element Types

*   **Express Checkout Element**: An embeddable component for accepting payments through one-click payment buttons.
*   **Link Authentication Element**: Used for collecting customer authentication information.
*   **Address Element**: An embeddable component for collecting local and international billing and shipping addresses.
*   **Payment Element**: A pre-built UI component that collects all the necessary payment details from your customers.
*   **Tax ID Element**: Used for collecting tax identification numbers.

### Creating and Retrieving Elements

The `elements` object provides methods for creating and retrieving different types of Elements.

*   **`elements.create(type: string, options?: object)`**: Creates an instance of an individual Element.
    *   **`type`**: The type of Element to create (e.g., `'expressCheckout'`, `'linkAuthentication'`, `'address'`, `'payment'`, `'taxId'`).
    *   **`options`**: Optional configuration for the Element.

*   **`elements.getElement(type: string, options?: object)`**: Retrieves a previously created Element.
    *   **`type`**: The type of Element to retrieve (e.g., `'payment'`, `'expressCheckout'`, `'linkAuthentication'`, `'address'`, `'taxId'`).
    *   **`options`**: Optional configuration, required for `address` Elements if using multiple instances.

### Element Methods

Individual Element instances offer various methods for interaction:

*   **`element.collapse()`**: Collapses the Payment Element into a row of payment method tabs.
*   **`element.getValue()`**: Validates and retrieves form values from a Tax ID Element.
*   **`element.blur()`**: Blurs the Element.
*   **`element.update()`**: Triggers an update for the Element.

### Element Events

Elements emit various events that you can listen to for responding to user interactions and state changes.

*   **`element.on(event: string, handler: function)`**: Attaches an event listener to an Element.

    *   **`update-end`**: Triggered when the call to `elements.update()` is complete.
    *   **`change`**: Triggered when any value in the change event payload changes. Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement` in Custom Checkout.
    *   **`ready`**: Triggered when the Element is fully rendered and methods like `focus()` and `update()` can be called. For `expressCheckout` Elements, `availablePaymentMethods` is provided in the event object.
    *   **`focus`**: Triggered when the Element gains focus.
    *   **`blur`**: Triggered when the Element loses focus.
    *   **`escape`**: Triggered when the escape key is pressed within an Element.
    *   **`click`**: Triggered when the Element is clicked.
    *   **`loaderror`**: Triggered when the Element fails to load. 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**:
    *   **`confirm`**: Triggered when the customer finalizes their payment. The handler receives an event object with details like `elementType`, `expressPaymentType`, `paymentFailed`, `reason`, `message`, `billingDetails`, and `shippingAddress`.
    *   **`cancel`**: Triggered when the payment interface is dismissed. This can occur even after payment authorization.
    *   **`shippingaddresschange`**: Triggered when the customer selects a new shipping address. Not available for Elements with Checkout Sessions.
    *   **`shippingratechange`**: Triggered when the customer selects a new shipping rate. Not available for Elements with Checkout Sessions.

### Custom Checkout Elements

Custom Checkout provides specific Elements for building a tailored checkout experience.

*   **`checkout.createBillingAddressElement(options?: object)`**: Creates a Billing Address Element.
*   **`checkout.createShippingAddressElement(options?: object)`**: Creates a Shipping Address Element.
*   **`checkout.createCurrencySelectorElement()`**: Creates a Currency Selector Element.
*   **`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.

Custom Checkout Elements also support the following events: `change`, `ready`, `focus`, `blur`, `escape`, and `loaderror`.

### Embedded Checkout

Embedded Checkout offers methods for mounting, unmounting, and destroying the checkout experience.

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

### Custom Checkout Actions

The `actions` object in Custom Checkout provides methods to interact with the Checkout Session.

*   **`actions.getSession()`**: Returns an object containing 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?: 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 makes a request to your server to update the Checkout Session.

### Custom Checkout Events

*   **`checkout.on(event: 'change', handler: function)`**: Listens for changes to Checkout Session data, such as shipping address changes. The handler receives a Checkout Session object.

### React Stripe.js Checkout

The `react-stripe-js` library provides similar functionalities for managing Checkout.

*   **`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?: object)`**: 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 on the server.

### Payment Request Events

*   **`PaymentRequest` instances emit various types of events.**

### Viewport Meta Tag Requirements

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