## JavaScript Elements API

This section covers the JavaScript Elements API, which allows you to create and manage various UI components for collecting payment and address information.

### Elements Object

The `elements` object is your primary interface for creating and retrieving 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'`, `'taxId'`).
    *   `options`: Optional configuration for the Element.
*   **`elements.getElement(type: string, options?: object)`**: Retrieves a previously created Element instance.
    *   `type`: The type of Element to retrieve.
    *   `options`: Optional parameters for retrieving specific Element instances (e.g., `mode` for `address`).

#### Specific Element Creation and Retrieval:

*   **Express Checkout Element**:
    *   `elements.create('expressCheckout', options?: object)`: Creates an Express Checkout Element.
    *   `elements.getElement('expressCheckout')`: Retrieves an existing Express Checkout Element.
*   **Link Authentication Element**:
    *   `elements.create('linkAuthentication', options?: object)`: Creates a Link Authentication Element.
    *   `elements.getElement('linkAuthentication')`: Retrieves an existing Link Authentication Element.
*   **Address Element**:
    *   `elements.create('address', options?: object)`: Creates an Address Element.
    *   `elements.getElement('address', options?: object)`: Retrieves an existing Address Element.
*   **Payment Element**:
    *   `elements.getElement('payment')`: Retrieves a previously created Payment Element.
*   **Tax ID Element**:
    *   `elements.getElement('taxId')`: Retrieves a previously created Tax ID Element.

### Individual Element Methods and Events

Once you have an Element instance, you can interact with it using various methods and listen for events.

#### Common Element Methods:

*   **`element.blur()`**: Blurs the Element.
*   **`element.focus()`**: Focuses the Element.
*   **`element.update(data?: object)`**: Updates the Element's appearance or data.
*   **`element.getValue()`**: Retrieves the value from an Element (e.g., Tax ID Element).

#### Common Element Events:

*   **`element.on('change', handler)`**: Triggered when the value within an Element changes.
*   **`element.on('ready', handler)`**: Triggered when the Element is fully rendered and ready for interaction.
*   **`element.on('focus', handler)`**: Triggered when the Element gains focus.
*   **`element.on('blur', handler)`**: Triggered when the Element loses focus.
*   **`element.on('escape', handler)`**: Triggered when the escape key is pressed within an Element.
*   **`element.on('click', handler)`**: Triggered when the Element is clicked.
*   **`element.on('loaderror', handler)`**: Triggered when the Element fails to load. This event is supported by specific Elements like `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber`.

#### Express Checkout Element Specific Events:

*   **`expressCheckoutElement.on('confirm', handler)`**: Triggered when the customer finalizes their payment.
*   **`expressCheckoutElement.on('cancel', handler)`**: Triggered when the payment interface is dismissed.
*   **`expressCheckoutElement.on('shippingaddresschange', handler)`**: Triggered when the customer selects a new shipping address.
*   **`expressCheckoutElement.on('shippingratechange', handler)`**: Triggered when the customer selects a new shipping rate.

#### Update-end Event:

*   **`elements.on('update-end', handler)`**: Triggered when the call to `elements.update()` is complete.

### Embedded Checkout

The Embedded Checkout API allows you to integrate Stripe Checkout directly into your website.

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

#### Custom Checkout Actions:

The `actions` object provides methods for interacting 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)`**: Updates the quantity of a line item.
*   **`actions.updateShippingOption(shippingOption?: string)`**: Updates the selected shipping option.
*   **`actions.runServerUpdate(userFunction: function)`**: Wraps an async function to update the Checkout Session on your server.

#### Custom Checkout Elements:

*   **`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 Appearance and Fonts:

*   **`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 Events:

*   **`checkout.on('change', handler)`**: Listens for changes to the Checkout Session data.

#### Custom Checkout Element Events:

These events are specific to Elements created within the Custom Checkout context.

*   **`element.on('change', handler)`**: Triggered when the value within a Custom Checkout Element changes. Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.
*   **`element.on('ready', handler)`**: Triggered when a Custom Checkout Element is fully rendered.
*   **`element.on('focus', handler)`**: Triggered when a Custom Checkout Element gains focus.
*   **`element.on('blur', handler)`**: Triggered when a Custom Checkout Element loses focus.
*   **`element.on('escape', handler)`**: Triggered when the escape key is pressed within a Custom Checkout Element.
*   **`element.on('loaderror', handler)`**: Triggered when a Custom Checkout Element fails to load.
*   **`expressCheckoutElement.on('confirm', handler)`**: Triggered from the Express Checkout Element when the customer finalizes their payment.
*   **`expressCheckoutElement.on('cancel', handler)`**: Triggered from the Express Checkout Element when the payment interface is dismissed.

### React Stripe.js Checkout

This section details methods available for managing Checkout within a React Stripe.js integration.

*   **`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)`**: Updates 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 your server.

### PaymentRequest Events

*   **`PaymentRequest` instances emit several different types of events.** (Specific events are not detailed in the provided documentation snippets).

### Viewport Meta Tag Requirements

To ensure a good user experience for 3D Secure on all devices, you should set your page's viewport `width` to `device-width` using the viewport meta tag. Ensure `width=device-width` is included in your viewport configuration.