# Elements

Stripe Elements are prebuilt UI components that you can embed in your website to collect payments. They provide a secure and customizable way to accept payments without handling sensitive card details directly.

## Core Concepts

*   **Elements:** Individual UI components that represent specific input fields (e.g., card number, expiry date, CVC) or payment methods (e.g., Express Checkout, Link Authentication).
*   **Element Instances:** When you create an Element, you get an instance of that Element that you can then mount to your page and interact with.
*   **`elements` Object:** A central object used to create, retrieve, and manage Element instances.

## Element Types

The following table lists the available Element types:

| Element Type             | Description                                                                                                 |
| :----------------------- | :---------------------------------------------------------------------------------------------------------- |
| `payment`                | A versatile Element for collecting payment details.                                                         |
| `expressCheckout`        | An embeddable component for accepting payments through one-click payment buttons (e.g., Apple Pay, Google Pay). |
| `linkAuthentication`     | An Element for collecting customer email addresses for Link.                                                |
| `address`                | An embeddable component for collecting local and international billing and shipping addresses.                |
| `taxId`                  | An Element for collecting tax identification numbers.                                                       |
| `card`                   | A classic Element for collecting card details.                                                              |
| `cardNumber`             | A specific Element for collecting only the card number.                                                     |
| `currencySelector`       | An Element that allows customers to select their preferred currency.                                        |

## Creating Elements

You can create Element instances using the `elements.create()` method:

```javascript
// Create a Payment Element
const paymentElement = elements.create('payment');

// Create an Express Checkout Element
const expressCheckoutElement = elements.create('expressCheckout', {
  // options for Express Checkout
});
```

## Retrieving Elements

If you need to access a previously created Element, you can use the `elements.getElement()` method:

```javascript
// Get a Payment Element
const paymentElement = elements.getElement('payment');

// Get an Express Checkout Element
const expressCheckoutElement = elements.getElement('expressCheckout');
```

## Element Events

Elements emit various events that allow you to respond to user interactions and changes in the Element's state.

### Common Element Events

*   **`ready`**: Triggered when the Element is fully rendered and ready to be used.
*   **`change`**: Triggered when any value within the Element changes.
*   **`focus`**: Triggered when the Element gains focus.
*   **`blur`**: Triggered when the Element loses focus.
*   **`escape`**: Triggered when the escape key is pressed within the Element.
*   **`loaderror`**: Triggered when the Element fails to load.

### Express Checkout Element Specific Events

*   **`confirm`**: Triggered when the customer finalizes their payment.
*   **`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.

## Element Methods

Element instances provide methods to interact with them:

*   **`mount(domElement)`**: Mounts the Element to a specified DOM element.
*   **`unmount()`**: Unmounts the Element from the DOM.
*   **`destroy()`**: Removes the Element from the DOM and cleans up its resources.
*   **`blur()`**: Blurs the Element.
*   **`focus()`**: Focuses the Element.
*   **`update(data)`**: Updates the Element with new data.
*   **`getValue()`**: Retrieves the current value from the Element (e.g., for Tax ID Element).
*   **`collapse()`**: Collapses the Payment Element into a row of payment method tabs.

## Custom Checkout

Custom Checkout provides a more flexible way to build your payment flow using individual Elements.

### Creating and Managing Custom Checkout Elements

*   **`checkout.createBillingAddressElement(options)`**: Creates a Billing Address Element.
*   **`checkout.createShippingAddressElement(options)`**: Creates a Shipping Address Element.
*   **`checkout.createCurrencySelectorElement()`**: Creates a Currency Selector Element.
*   **`checkout.getPaymentElement()`**: Retrieves the Payment Element.
*   **`checkout.getBillingAddressElement()`**: Retrieves the Billing Address Element.
*   **`checkout.getShippingAddressElement()`**: Retrieves the Shipping Address Element.
*   **`checkout.getExpressCheckoutElement()`**: Retrieves the Express Checkout Element.
*   **`checkout.getCurrencySelectorElement()`**: Retrieves the Currency Selector Element.

### Custom Checkout Actions

The `actions` object provides methods to interact with the Checkout Session:

*   **`actions.getSession()`**: Reads session data.
*   **`actions.applyPromotionCode(promotionCode)`**: Applies a promotion code.
*   **`actions.removePromotionCode()`**: Removes the applied promotion code.
*   **`actions.updateShippingAddress(shippingAddress)`**: Updates the customer's shipping address.
*   **`actions.updateBillingAddress(billingAddress)`**: Updates the customer's billing address.
*   **`actions.updateEmail(email)`**: Updates the customer's email address.
*   **`actions.updatePhoneNumber(phoneNumber)`**: Updates the customer's phone number.
*   **`actions.updateTaxIdInfo(taxIdInfo)`**: Updates the customer's business name and tax ID.
*   **`actions.updateLineItemQuantity(options)`**: Updates the quantity of a line item.
*   **`actions.updateShippingOption(shippingOption)`**: Updates the selected shipping option.
*   **`actions.runServerUpdate(userFunction)`**: Wraps an async function to update the Checkout Session on your server.

### Custom Checkout Appearance and Fonts

*   **`checkout.changeAppearance(appearance)`**: Changes the visual customization of Elements using the Appearance API.
*   **`checkout.loadFonts(fonts)`**: Loads additional custom fonts into Elements.

### Custom Checkout Events

*   **`checkout.on('change', handler)`**: Listens for changes in the Checkout Session data.

## Embedded Checkout

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

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

## Viewport Meta Tag

For an optimal user experience with 3D Secure, ensure your page includes the viewport meta tag with `width=device-width`:

```html
<meta name="viewport" content="width=device-width, initial-scale=1.0">
```