## Elements

This section covers the various Elements available in the Stripe JavaScript SDK, including how to create, retrieve, and interact with them.

### Creating and Retrieving Elements

*   **`elements.create(type: string, options?: object)`**: Creates an instance of an individual `Element`. You specify the `type` of Element and an optional `options` object. (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)
*   **`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. The `mode` option is required when using multiple Address Elements. (Page 14)
*   **`elements.getElement(type: 'taxId')`**: Retrieves a previously created Tax ID Element. (Page 15)
*   **`elements.on(event: 'update-end', handler: function)`**: Triggered when the call to `elements.update()` is complete. (Page 1)

### Specific Element Types

#### Express Checkout Element

*   **The Express Checkout Element**: An embeddable component for accepting payments through one-click payment buttons. (Page 4)
*   **`expressCheckoutElement.on(event: string, handler: function)`**: Attaches event listeners to the Express Checkout Element.
    *   **`confirm` event**: Triggered when the customer finalizes their payment. Use this event to trigger payment confirmation. (Page 7)
    *   **`cancel` event**: Triggered when the payment interface is dismissed. (Page 8)
    *   **`shippingaddresschange` event**: Triggered when the customer selects a new shipping address. (Page 9)
    *   **`shippingratechange` event**: Triggered when the customer selects a new shipping rate. (Page 10)

#### Link Authentication Element

*   **Create the Link Authentication Element**: Creates an instance of the Link Authentication Element, optionally with default values for contact information. (Page 11)
*   **Get a Link Authentication Element**: Retrieves a previously created Link Authentication Element. (Page 12)

#### Address Element

*   **The Address Element**: An embeddable component for collecting local and international billing and shipping addresses. (Page 13)
*   **Get an Address Element**: Retrieves a previously created Address Element, with an optional `mode` for distinguishing multiple instances. (Page 14)

#### Tax ID Element

*   **Retrieve a Tax ID Element**: Retrieves a previously created Tax ID Element. (Page 15)
*   **`element.getValue()`**: Validates and retrieves form values from a Tax ID Element. (Page 16)

### Element Methods and Events

*   **`element.collapse()`**: Collapses the Payment Element into a row of payment method tabs. (Page 3)
*   **`element.blur()`**: Blurs the [Element](https://docs.stripe.com/js/element.md). (Page 19)
*   **`element.on(event: 'change', handler: function)`**: The change event is 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 and methods like `element.focus()` and `element.update()` can be called. (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)`**: Handles click events on an Element. (Page 25)
*   **`element.on(event: 'loaderror', handler: function)`**: Triggered when the `Element` fails to load. This event is emitted by specific Elements like `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber`. (Page 26)

### Embedded Checkout

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

#### Custom Checkout Actions

*   **`actions.getSession()`**: Returns an object containing data about the Checkout Session. (Page 30)
*   **`actions.applyPromotionCode(promotionCode: string)`**: Applies a promotion code to the Checkout Session. (Page 31)
*   **`actions.removePromotionCode()`**: Removes the currently applied promotion code. (Page 32)
*   **`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)
*   **`actions.updateLineItemQuantity(options: object)`**: Changes the quantity of a line item. (Page 38)
*   **`actions.updateShippingOption(shippingOption?: string)`**: Updates the selected shipping option. (Page 39)
*   **`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

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

#### Custom Checkout 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 Element Events

*   **`element.on(event: 'change', handler: function)`**: The change event is triggered when any value in the change event payload changes for `paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`. (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)
*   **`expressCheckoutElement.on(event: string, handler: function)`**: Event listeners for the Express Checkout Element within Custom Checkout.
    *   **`confirm` event**: Triggered from the Express Checkout Element when the customer finalizes their payment. (Page 59)
    *   **`cancel` event**: Triggered from the Express Checkout Element when the payment interface is dismissed. (Page 60)

### React Stripe.js Checkout Actions

These actions are specific to the React Stripe.js library's checkout integration.

*   **`applyPromotionCode(promotionCode: string)`**: Applies a promotion code to the Checkout Session. (Page 61)
*   **`removePromotionCode()`**: Removes the currently applied promotion code. (Page 62)
*   **`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)
*   **`updateLineItemQuantity(options: object)`**: Changes the quantity of a line item. (Page 68)
*   **`updateShippingOption(shippingOption?: string)`**: Updates the selected shipping option. (Page 69)
*   **`runServerUpdate(userFunction: function)`**: Wraps an async function that makes a request to your server to update the Checkout Session. (Page 70)

### PaymentRequest Events

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

### Viewport Meta Tag Requirements

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