# Elements API Reference

This section provides a comprehensive reference for the Elements API, covering various components, methods, and events for integrating Stripe payments into your application.

## Elements Object

The `elements` object is the primary interface for creating and managing Elements.

### Creating 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`: An object containing configuration options specific to the Element type.

### Retrieving Elements

*   **`elements.getElement(type: string, options?: object)`**: Retrieves a previously created Element instance.
    *   `type`: The type of Element to retrieve (e.g., 'payment', 'expressCheckout', 'linkAuthentication', 'address', 'taxId').
    *   `options`: Optional, used for retrieving specific instances of Elements like the Address Element when multiple are present.

## Individual Element Types

### Express Checkout Element

*   **The Express Checkout Element**: An embeddable component for accepting payments through one-click payment buttons.
    *   **`elements.create('expressCheckout', options?: object)`**: Creates an instance of the Express Checkout Element.
        *   `options`:
            *   `allowedShippingCountries`: Restricts allowed shipping countries.
            *   `applePay`: Apple Pay specific options.
            *   `recurringPaymentRequest`: Options for setting up recurring payments.
            *   `deferredPaymentRequest`: Options for setting up deferred payments.
            *   `automaticReloadPaymentRequest`: Options for setting up automatic reload payments.
            *   `billingAddressRequired`: Controls whether the billing address is collected.

### Payment Element

*   **`elements.getElement(type: 'payment')`**: Retrieves a previously created Payment Element.

### Link Authentication Element

*   **`elements.create('linkAuthentication', options?: object)`**: Creates an instance of the Link Authentication Element.
    *   `options`:
        *   `defaultValues`: Pre-fills contact information.
*   **`elements.getElement(type: 'linkAuthentication')`**: Retrieves a previously created Link Authentication Element.

### Address Element

*   **The Address Element**: An embeddable component for collecting billing and shipping addresses.
    *   **`elements.getElement(type: 'address', options?: object)`**: Retrieves a previously created Address Element.
        *   `options`:
            *   `mode`: Required when using multiple Address Elements.

### Tax ID Element

*   **`elements.getElement(type: 'taxId')`**: Retrieves a previously created Tax ID Element.
    *   **`element.getValue()`**: Validates and retrieves form values from a Tax ID Element.

## Element Methods

These methods can be called on individual Element instances.

*   **`element.blur()`**: Blurs the Element.
*   **`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.
*   **`elements.update()`**: Completes a call to `elements.update()`.

## Element Events

Elements emit various events that you can listen to for real-time updates and user interactions.

*   **`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.
*   **`element.on(event: 'ready', handler: function)`**: Triggered when the Element is fully rendered.
    *   The `event` object may contain `availablePaymentMethods` for the `expressCheckout` Element.
*   **`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 an Element is clicked.
*   **`element.on(event: 'loaderror', handler: function)`**: Triggered when the Element fails to load. This event is supported by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements.
    *   The `event` object contains `elementType` and an `error` object.

### Express Checkout Element Specific Events

*   **`expressCheckoutElement.on(event: 'confirm', handler: function)`**: Triggered when the customer finalizes their payment.
    *   The `event` object includes `elementType`, `expressPaymentType`, `paymentFailed(payload)`, `reason`, `message`, `billingDetails`, and `shippingAddress`.
*   **`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.
    *   The `event` object includes `elementType` and `resolve(payload)`.
*   **`expressCheckoutElement.on(event: 'shippingratechange', handler: function)`**: Triggered when the customer selects a new shipping rate.
    *   The `event` object includes `elementType` and `resolve(payload)`.

## Custom Checkout

Custom Checkout provides more flexibility in building your payment flow.

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

### Actions

The `actions` object 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.
*   **`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.

### Creating Elements within Custom Checkout

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

### Retrieving Elements within Custom Checkout

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

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

*   **`element.on(event: 'change', handler: function)`**: Triggered when any value in the change event payload changes. Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.
*   **`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.

## React Stripe.js Checkout

This section details the checkout-related methods available when using React Stripe.js.

*   **`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 that makes a request to your server to update the Checkout Session.

## PaymentRequest Events

*   **`PaymentRequest` instances emit several different types of events.**

## Viewport Meta Tag Requirements

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