# Elements and Checkout

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

## Elements

Elements are embeddable UI components that allow you to securely collect payment information.

### Core Element Functionality

*   **`elements.create(type: string, options?: object)`**: Creates an instance of an individual `Element`.
*   **`elements.getElement(type: string, options?: object)`**: Retrieves a previously created `Element`.

### Specific Element Types

*   **Express Checkout Element**: For accepting payments through one-click payment buttons.
    *   `elements.create('expressCheckout', options?: object)`
    *   `elements.getElement('expressCheckout')`
*   **Payment Element**: (Implicitly referenced through `elements.getElement(type: 'payment')`) Retrieves a previously created Payment Element.
*   **Link Authentication Element**: For collecting customer authentication details.
    *   `elements.create('linkAuthentication', options?: object)`
    *   `elements.getElement('linkAuthentication')`
*   **Address Element**: For collecting billing and shipping addresses.
    *   `elements.getElement('address', options?: object)`
*   **Tax ID Element**: For collecting tax identification numbers.
    *   `elements.getElement('taxId')`
    *   `element.getValue()`: Validates and retrieves form values from a Tax ID Element.

### 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.
*   **`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 on a click event.
*   **`element.on(event: 'loaderror', handler: function)`**: Triggered when the `Element` fails to load. (Supported by `payment`, `linkAuthentication`, `address`, `expressCheckout`, `currencySelector`, `taxId`, `card`, and `cardNumber` Elements).

### Element Methods

*   **`element.collapse()`**: Collapses the Payment Element into a row of payment method tabs.
*   **`element.blur()`**: Blurs the `Element`.

## Express Checkout Element Events

Specific events for the Express Checkout Element:

*   **`expressCheckoutElement.on(event: 'confirm', handler: function)`**: Triggered when the customer finalizes their payment.
*   **`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.
*   **`expressCheckoutElement.on(event: 'shippingratechange', handler: function)`**: Triggered when the customer selects a new shipping rate.

## Custom Checkout

Custom Checkout provides a flexible way to build your own checkout experience.

### Checkout Actions

*   **`actions.getSession()`**: Returns an object containing data about the Checkout Session.
*   **`actions.applyPromotionCode(promotionCode: string)`**: Applies a promotion code to the Checkout Session.
*   **`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 to update the Checkout Session on your server.

### Creating Custom Checkout Elements

*   **`checkout.createBillingAddressElement(options?: object)`**: Creates an instance of a Billing Address Element.
*   **`checkout.createShippingAddressElement(options?: object)`**: Creates an instance of a Shipping Address Element.
*   **`checkout.createCurrencySelectorElement()`**: Creates an instance of a Currency Selector Element.

### Getting Custom Checkout Elements

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

*   **`checkout.on(event: 'change', handler: function)`**: Triggered when Checkout Session data changes.

### Custom Checkout Element Events

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

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

## 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.
*   **`checkout.unmount()`**: Unmounts Checkout from the DOM.
*   **`checkout.destroy()`**: Removes Checkout from the DOM and destroys it.

## React Stripe.js Checkout

This section covers checkout functionalities specifically for the React Stripe.js library.

### React Checkout Actions

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

## Payment Request Events

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

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