## Elements

This section covers the various Elements available in the Stripe JavaScript SDK, which are pre-built UI components for collecting payment information and other customer details.

### Creating and Managing Elements

*   **`elements.create(type: string, options?: object)`**: Creates an instance of an individual `Element`. This is a general-purpose method for creating various types of elements.
*   **`elements.getElement(type: string, options?: object)`**: Retrieves a previously created `Element`. This is useful for re-accessing existing elements.

#### Specific Element Creation and Retrieval:

*   **Express Checkout Element**:
    *   **`elements.create('expressCheckout', options?: object)`**: Creates an instance of the Express Checkout Element.
    *   **`elements.getElement(type: 'expressCheckout')`**: Retrieves a previously created Express Checkout Element.
*   **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.
    *   **`elements.getElement(type: 'linkAuthentication')`**: Retrieves a previously created Link Authentication Element.
*   **Address Element**:
    *   **`elements.getElement(type: 'address', options?: object)`**: Retrieves a previously created Address Element.
*   **Tax ID Element**:
    *   **`elements.getElement(type: 'taxId')`**: Retrieves a previously created Tax ID Element.

### Element Interactions and Events

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

#### Common Element Events:

*   **`change`**: Triggered when any value in the change event payload changes.
*   **`ready`**: Triggered when the `Element` is fully rendered and methods like `focus()` and `update()` can be called.
*   **`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 an `Element` is clicked.
*   **`loaderror`**: Triggered when the `Element` fails to load. This event is emitted by specific Elements like `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber`.

#### Specific Element Events:

*   **Update-end event**:
    *   **`elements.on('update-end', handler: function)`**: Triggered when the call to `elements.update()` is complete.
*   **Express Checkout Element Events**:
    *   **`confirm`**: Triggered when the customer finalizes their payment. Use this to trigger payment confirmation.
    *   **`cancel`**: Triggered when the payment interface is dismissed.
    *   **`shippingaddresschange`**: Triggered when the customer selects a new shipping address.
    *   **`shippingratechange`**: Triggered when the customer selects a new shipping rate.

### Tax ID Element Specifics

*   **`element.getValue()`**: Validates and retrieves form values from a Tax ID Element.

### Embedded Checkout

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

*   **`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 line item quantities.
*   **`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 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 Element Events:

*   **`element.on('change', handler: function)`**: Change event for custom checkout elements.
*   **`element.on('ready', handler: function)`**: Ready event for custom checkout elements.
*   **`element.on('focus', handler: function)`**: Focus event for custom checkout elements.
*   **`element.on('blur', handler: function)`**: Blur event for custom checkout elements.
*   **`element.on('escape', handler: function)`**: Escape event for custom checkout elements.
*   **`element.on('loaderror', handler: function)`**: LoadError event for custom checkout elements.
*   **`expressCheckoutElement.on('confirm', handler: function)`**: Confirm event for the Express Checkout Element in custom checkout.
*   **`expressCheckoutElement.on('cancel', handler: function)`**: Cancel event for the Express Checkout Element in custom checkout.

### React Stripe.js 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)`**: Updates line item quantities.
*   **`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.

### Payment Request Events

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

### Viewport Meta Tag Requirements

*   In order to provide a great user experience for 3D Secure on all devices, you should set your page's viewport `width` to `device-width` with the viewport meta tag.