## Elements

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

### Creating Elements

Stripe.js provides methods to create different types of Elements, which are UI components for collecting payment information.

*   **`elements.create(type: string, options?: object)`**: This is a general method for creating an instance of an individual `Element`. It requires the `type` of Element to create and an optional `options` object.
    *   **`elements.create(type: 'expressCheckout', options?: object)`**: Specifically creates an instance of the Express Checkout Element, used for one-click payment buttons. It accepts various options for customization, including `allowedShippingCountries`, `applePay`, `recurringPaymentRequest`, `paymentDescription`, `managementURL`, `regularBilling`, `amount`, `label`, `recurringPaymentStartDate`, `recurringPaymentEndDate`, `recurringPaymentIntervalUnit`, `recurringPaymentIntervalCount`, `trialBilling`, `billingAgreement`, `deferredPaymentRequest`, `amountType`, `freeCancellationDate`, `freeCancellationDateTimeZone`, and `automaticReloadPaymentRequest`.
    *   **`elements.create(type: 'linkAuthentication', options?: object)`**: Creates an instance of the Link Authentication Element. It accepts an `options` object, which can include `defaultValues` for pre-filling contact information like `email`.
    *   **`elements.create(type: 'payment', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'address', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'taxId', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'card', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'cardNumber', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'currencySelector', options?: object)`**: (Implicitly covered by other methods, but `elements.create` is the general function)
    *   **`elements.create(type: 'issuing', options: object)`**: Creates an instance of an individual Issuing Element.

### Retrieving Elements

You can retrieve previously created Elements using their type.

*   **`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. The `options` object may include a `mode` if multiple Address Elements are used.
*   **`elements.getElement(type: 'taxId')`**: Retrieves a previously created Tax ID Element.

### Element Methods

Elements provide various methods to interact with them.

*   **`element.blur()`**: Blurs the Element, removing focus.
*   **`element.getValue()`**: Validates and retrieves form values from a Tax ID Element. Input validation errors are displayed by their associated fields.
*   **`element.collapse()`**: Collapses the Payment Element into a row of payment method tabs.
*   **`element.update()`**: (Mentioned in the `update-end` event) Used to update an Element.

### Element Events

Elements can emit events to notify your application of changes or user interactions.

*   **`element.on(event: 'update-end', handler: function)`**: Triggered when the call to `elements.update()` is complete. The `handler` is a callback function.
*   **`element.on(event: 'change', handler: function)`**: Triggered when any value in the change event payload changes. The payload contains certain keys and Element-specific keys.
*   **`element.on(event: 'ready', handler: function)`**: Triggered when the Element is fully rendered and methods like `element.focus()` and `element.update()` can be called. The `handler` receives an event object with `elementType` and, for `expressCheckout`, `availablePaymentMethods` (including `link`, `applePay`, `googlePay`, `paypal`, `amazonPay`, `klarna`).
*   **`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 the Element fails to load. This event is emitted by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements. The `handler` receives an event object with `elementType` and an `error` object.

### Express Checkout Element Specifics

*   **The Express Checkout Element**: An embeddable component for accepting payments through one-click payment buttons.
*   **`expressCheckoutElement.on(event: 'confirm', handler: function)`**: Triggered when the customer finalizes their payment. The `handler` receives an event object with `elementType`, `expressPaymentType`, `paymentFailed(payload)`, `reason`, `message`, `billingDetails` (including `name`, `email`, `phone`, `address`), and `shippingAddress`.
*   **`expressCheckoutElement.on(event: 'cancel', handler: function)`**: Triggered when the payment interface is dismissed. This can occur even after payment authorization. If used for order cancellation, ensure payment refunds are also handled.
*   **`expressCheckoutElement.on(event: 'shippingaddresschange', handler: function)`**: Triggered when the customer selects a new shipping address. This event is not available for Elements with Checkout Sessions. The `handler` receives an event object with `elementType` and a `resolve(payload)` function.
*   **`expressCheckoutElement.on(event: 'shippingratechange', handler: function)`**: Triggered when the customer selects a new shipping rate. This event is not available for Elements with Checkout Sessions. The `handler` receives an event object with `elementType` and a `resolve(payload)` function.

### Address Element

*   **The Address Element**: An embeddable component for collecting local and international billing and shipping addresses.

### Custom Checkout Elements

Custom Checkout provides methods to create and manage specific Elements within a custom checkout flow.

*   **`checkout.createBillingAddressElement(options?: object)`**: Creates a Billing Address Element. Options include `contacts` (with `name`, `address`, `line1`, `line2`, `city`, `state`, `postal_code`, `country`, `phone`) and `display` options for `name`.
*   **`checkout.createShippingAddressElement(options?: object)`**: Creates a Shipping Address Element with similar `contacts` and `display` options as the Billing 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.
*   **`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

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

*   **`element.on(event: 'change', handler: function)`**: Triggered when values change in `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.
*   **`element.on(event: 'ready', handler: function)`**: Triggered when the Element is fully rendered. The `handler` receives an event object with `elementType`.
*   **`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. The `handler` receives an event object with `elementType` and an `error` object.
*   **`expressCheckoutElement.on(event: 'confirm', handler: function)`**: Triggered from the Express Checkout Element when the customer finalizes their payment. The `handler` receives an event object with `elementType`, `expressPaymentType`, `paymentFailed(payload)`, `reason`, `message`, `billingDetails`, `shippingAddress`, and `shippingRate`.
*   **`expressCheckoutElement.on(event: 'cancel', handler: function)`**: Triggered from the Express Checkout Element when the payment interface is dismissed.

### Embedded Checkout

Embedded Checkout provides methods for mounting, unmounting, and destroying the checkout interface.

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

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

*   **`actions.getSession()`**: Returns an object containing data about the Checkout Session.
*   **`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?: )`**: 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, with a 20-second timeout.

### Custom Checkout Events

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

### React Stripe.js Checkout

This section covers checkout-related methods within the `react-stripe.js` library.

*   **`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 on your server.

### Payment Request Events

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

### Viewport Meta Tag Requirements

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