## Elements and Checkout

This section covers the various Elements and Checkout functionalities available in the Stripe JavaScript SDK.

### Elements

Elements are embeddable UI components that allow you to collect payment and other sensitive information directly on your website.

#### Core Element Functionality

*   **Creating Elements:**
    *   `elements.create(type: string, options?: object)`: Creates an instance of an individual `Element`. (Page 18)
    *   `elements.create(type: 'expressCheckout', options?: object)`: Creates an instance of the Express Checkout Element. (Page 5)
    *   `elements.create(type: 'linkAuthentication', options?: object)`: Creates an instance of the Link Authentication Element. (Page 11)
*   **Retrieving Elements:**
    *   `elements.getElement(type: 'payment')`: Retrieves a previously created Payment Element. (Page 2)
    *   `elements.getElement(type: 'expressCheckout')`: Retrieves a previously created Express Checkout Element. (Page 6)
    *   `elements.getElement(type: 'linkAuthentication')`: Retrieves a previously created Link Authentication Element. (Page 12)
    *   `elements.getElement(type: 'address', options?: object)`: Retrieves a previously created Address Element. (Page 14)
    *   `elements.getElement(type: 'taxId')`: Retrieves a previously created Tax ID Element. (Page 15)
*   **Element Types:**
    *   The Address Element is an embeddable component for collecting local and international billing and shipping addresses. (Page 13)
    *   The Express Checkout Element is an embeddable component for accepting payments through one-click payment buttons. (Page 4)
*   **Element Methods:**
    *   `element.blur()`: Blurs the [Element](https://docs.stripe.com/js/element.md). (Page 19)
    *   `element.collapse()`: Collapses the Payment Element into a row of payment method tabs. (Page 3)
    *   `element.getValue()`: Validates and retrieves form values from a Tax ID Element. (Page 16)
    *   `elements.on(event: 'update-end', handler: function)`: Triggered when the call to `elements.update()` is complete. (Page 1)
*   **Element Events:**
    *   `element.on(event: 'change', handler: function)`: Triggered when any value in the change event payload changes. (Page 20)
    *   `element.on(event: 'ready', handler: function)`: Triggered when the `Element` is fully rendered. (Page 21)
    *   `element.on(event: 'focus', handler: function)`: Triggered when the `Element` gains focus. (Page 22)
    *   `element.on(event: 'blur', handler: function)`: Triggered when the `Element` loses focus. (Page 23)
    *   `element.on(event: 'escape', handler: function)`: Triggered when the escape key is pressed within an Element. (Page 24)
    *   `element.on(event: 'click', handler: function)`: (Page 25)
    *   `element.on(event: 'loaderror', handler: function)`: Triggered when the `Element` fails to load. (Page 26)
    *   **Express Checkout Element Specific Events:**
        *   `expressCheckoutElement.on(event: 'confirm', handler: function)`: Triggered when the customer finalizes their payment. (Page 7)
        *   `expressCheckoutElement.on(event: 'cancel', handler: function)`: Triggered when the payment interface is dismissed. (Page 8)
        *   `expressCheckoutElement.on(event: 'shippingaddresschange', handler: function)`: Triggered when the customer selects a new shipping address. (Page 9)
        *   `expressCheckoutElement.on(event: 'shippingratechange', handler: function)`: Triggered when the customer selects a new shipping rate. (Page 10)

### Custom Checkout

Custom Checkout provides a flexible way to build a Stripe checkout experience using Elements.

#### Custom Checkout Actions

*   **Session Data:**
    *   `actions.getSession()`: Returns an object that contains data about the Checkout Session. (Page 30)
*   **Promotions:**
    *   `actions.applyPromotionCode(promotionCode: string)`: Applies a promotion code to the Checkout Session. (Page 31)
    *   `actions.removePromotionCode()`: Removes the currently applied promotion code. (Page 32)
*   **Customer Information Updates:**
    *   `actions.updateShippingAddress(shippingAddress: nullable object)`: Updates the customer's shipping address. (Page 33)
    *   `actions.updateBillingAddress(billingAddress: nullable object)`: Updates the customer's billing address. (Page 34)
    *   `actions.updateEmail(email: nullable string)`: Updates the customer's email address. (Page 35)
    *   `actions.updatePhoneNumber(phoneNumber: nullable string)`: Updates the customer's phone number. (Page 36)
    *   `actions.updateTaxIdInfo(taxIdInfo?: )`: Updates the customer's business name and tax ID. (Page 37)
*   **Line Items and Shipping:**
    *   `actions.updateLineItemQuantity(options: object)`: Changes the quantity of a line item. (Page 38)
    *   `actions.updateShippingOption(shippingOption?: string)`: Updates the selected shipping option. (Page 39)
*   **Server Updates:**
    *   `actions.runServerUpdate(userFunction: function)`: Wraps an async function that makes a request to your server to update the Checkout Session. (Page 40)

#### Custom Checkout Elements

*   **Creating Elements:**
    *   `checkout.createBillingAddressElement(options?: object)`: Creates an instance of a Billing Address Element. (Page 43)
    *   `checkout.createShippingAddressElement(options?: object)`: Creates an instance of a Shipping Address Element. (Page 44)
    *   `checkout.createCurrencySelectorElement()`: Creates an instance of a Currency Selector Element. (Page 45)
*   **Retrieving Elements:**
    *   `checkout.getPaymentElement()`: Gets the previously created Payment Element instance. (Page 46)
    *   `checkout.getBillingAddressElement()`: Gets the previously created Billing Address Element instance. (Page 47)
    *   `checkout.getShippingAddressElement()`: Gets the previously created Shipping Address Element instance. (Page 48)
    *   `checkout.getExpressCheckoutElement()`: Gets the previously created Express Checkout Element instance. (Page 49)
    *   `checkout.getCurrencySelectorElement()`: Gets the previously created Currency Selector Element instance. (Page 50)
*   **Appearance and Fonts:**
    *   `checkout.changeAppearance(appearance: object)`: Changes the visual customization of Elements using the Appearance API. (Page 51)
    *   `checkout.loadFonts(fonts: array)`: Loads additional custom fonts into Elements. (Page 52)

#### Custom Checkout Events

*   **General Checkout Events:**
    *   `checkout.on(event: 'change', handler: function)`: Triggered when Checkout Session data changes. (Page 42)
*   **Element Events within Custom Checkout:**
    *   `element.on(event: 'change', handler: function)`: Triggered when any value in the change event payload changes for supported Elements. (Page 53)
    *   `element.on(event: 'ready', handler: function)`: Triggered when the `Element` is fully rendered. (Page 54)
    *   `element.on(event: 'focus', handler: function)`: Triggered when the `Element` gains focus. (Page 55)
    *   `element.on(event: 'blur', handler: function)`: Triggered when the `Element` loses focus. (Page 56)
    *   `element.on(event: 'escape', handler: function)`: Triggered when the escape key is pressed within an `Element`. (Page 57)
    *   `element.on(event: 'loaderror', handler: function)`: Triggered when the `Element` fails to load. (Page 58)
    *   **Express Checkout Element Specific Events within Custom Checkout:**
        *   `expressCheckoutElement.on(event: 'confirm', handler: function)`: Triggered when the customer finalizes their payment. (Page 59)
        *   `expressCheckoutElement.on(event: 'cancel', handler: function)`: Triggered when the payment interface is dismissed. (Page 60)

### Embedded Checkout

Embedded Checkout allows you to embed Stripe Checkout directly into your website.

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

### React Stripe.js Checkout

This section details the checkout functionalities available when using the React Stripe.js library.

*   **Promotions:**
    *   `applyPromotionCode(promotionCode: string)`: Applies a promotion code to the Checkout Session. (Page 61)
    *   `removePromotionCode()`: Removes the currently applied promotion code. (Page 62)
*   **Customer Information Updates:**
    *   `updateShippingAddress(shippingAddress: nullable object)`: Updates the customer's shipping address. (Page 63)
    *   `updateBillingAddress(billingAddress: nullable object)`: Updates the customer's billing address. (Page 64)
    *   `updateEmail(email: nullable string)`: Updates the customer's email address. (Page 65)
    *   `updatePhoneNumber(phoneNumber: nullable string)`: Updates the customer's phone number. (Page 66)
    *   `updateTaxIdInfo(taxIdInfo?: )`: Updates the customer's business name and tax ID. (Page 67)
*   **Line Items and Shipping:**
    *   `updateLineItemQuantity(options: object)`: Changes the quantity of a line item. (Page 68)
    *   `updateShippingOption(shippingOption?: string)`: Updates the selected shipping option. (Page 69)
*   **Server Updates:**
    *   `runServerUpdate(userFunction: function)`: Wraps an async function that makes a request to your server to update the Checkout Session. (Page 70)

### Payment Request API

*   `PaymentRequest` instances emit several different types of events. (Page 71)

### Appendix

*   **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. (Page 72)