## Elements

This section covers the various Elements available in the Stripe JavaScript library, their creation, retrieval, and event handling.

### Creating Elements

*   **`elements.create(type: string, options?: object)`**: This is the primary method for creating instances of various Elements. It takes the `type` of Element to create and an optional `options` object for configuration.
    *   **`elements.create(type: 'expressCheckout', options?: object)`**: Specifically for creating an Express Checkout Element, which facilitates one-click payment buttons. It accepts various options like `allowedShippingCountries`, `applePay`, `recurringPaymentRequest`, `deferredPaymentRequest`, and `automaticReloadPaymentRequest` for detailed payment configurations.
    *   **`elements.create(type: 'linkAuthentication', options?: object)`**: Creates a Link Authentication Element, used for collecting customer contact information. It can accept `defaultValues` for pre-filling fields like email.
    *   **`elements.create(type: string, options: object)`** (from `/js/issuing_elements/create.md`): This method is specifically for creating Issuing Elements.

### 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. The `mode` option is required when using multiple Address Elements.
*   **`elements.getElement(type: 'taxId')`**: Retrieves a previously created Tax ID Element.

### Element Methods

*   **`element.collapse()`**: Collapses a 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, removing focus from it.
*   **`element.update()`**: Triggers an update for an Element. The `update-end` event is fired when this process is complete.

### Element Events

Elements emit various events that allow you to react to user interactions and state changes:

*   **`element.on(event: 'update-end', handler: function)`**: Fired when `elements.update()` completes.
*   **`element.on(event: 'change', handler: function)`**: Fired when any value within an Element changes.
*   **`element.on(event: 'ready', handler: function)`**: Fired when an Element is fully rendered and ready for interaction. For `expressCheckout` Elements, it can provide `availablePaymentMethods`.
*   **`element.on(event: 'focus', handler: function)`**: Fired when an Element gains focus.
*   **`element.on(event: 'blur', handler: function)`**: Fired when an Element loses focus.
*   **`element.on(event: 'escape', handler: function)`**: Fired when the escape key is pressed within an Element.
*   **`element.on(event: 'click', handler: function)`**: Fired when an Element is clicked.
*   **`element.on(event: 'loaderror', handler: function)`**: Fired when an Element fails to load. This event is supported by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements.

#### Express Checkout Element Specific Events

*   **`expressCheckoutElement.on(event: 'confirm', handler: function)`**: Triggered when a customer finalizes their payment. The handler receives an event object with details like `elementType`, `expressPaymentType`, `paymentFailed`, `billingDetails`, and `shippingAddress`.
*   **`expressCheckoutElement.on(event: 'cancel', handler: function)`**: Triggered when the payment interface is dismissed. This can occur even after payment authorization.
*   **`expressCheckoutElement.on(event: 'shippingaddresschange', handler: function)`**: Triggered when a customer selects a new shipping address. The handler receives a `resolve` function to validate the address.
*   **`expressCheckoutElement.on(event: 'shippingratechange', handler: function)`**: Triggered when a customer selects a new shipping rate. The handler receives a `resolve` function to validate the shipping rate.

### Specific Element Types

*   **The Address Element**: An embeddable component for collecting billing and shipping addresses.
*   **The Express Checkout Element**: An embeddable component for accepting payments via one-click payment buttons.
*   **The Link Authentication Element**: An embeddable component for collecting customer contact information.

### Embedded Checkout

*   **`checkout.mount(domElement: string | DOM element)`**: Attaches Checkout to the DOM.
*   **`checkout.unmount()`**: Unmounts Checkout from the DOM.
*   **`checkout.destroy()`**: Removes and destroys the Checkout instance.

#### Custom Checkout Actions

These actions are available within the context of a custom checkout integration:

*   **`actions.getSession()`**: Reads session data for 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)`**: Updates the quantity of a line item.
*   **`actions.updateShippingOption(shippingOption?: string)`**: Updates the selected shipping option.
*   **`actions.runServerUpdate(userFunction: function)`**: Wraps an async function that updates 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.
*   **`checkout.getBillingAddressElement()`**: Gets the previously created Billing Address Element.
*   **`checkout.getShippingAddressElement()`**: Gets the previously created Shipping Address Element.
*   **`checkout.getExpressCheckoutElement()`**: Gets the previously created Express Checkout Element.
*   **`checkout.getCurrencySelectorElement()`**: Gets the previously created Currency Selector Element.

#### 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(event: 'change', handler: function)`**: Triggered when Checkout Session data changes. The handler receives the updated Checkout Session object.

#### Custom Checkout Element Events

These events are specific to Elements created within a custom checkout integration:

*   **`element.on(event: 'change', handler: function)`**: Supported by `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.
*   **`element.on(event: 'ready', handler: function)`**: Triggered when the Element is ready.
*   **`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 upon payment finalization.
*   **`expressCheckoutElement.on(event: 'cancel', handler: function)`**: Triggered from the Express Checkout Element when the payment interface is dismissed.

### React Stripe.js Checkout Actions

These actions are available when using Stripe.js with React:

*   **`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 that updates the Checkout Session on your server.

### PaymentRequest Events

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

### Viewport Meta Tag Requirements

*   **Viewport meta tag requirements**: For optimal 3D Secure experience, ensure your page includes `width=device-width` in the viewport meta tag.