## Listen to Elements events

Communicate with your [Element](/js/custom_checkout/custom_checkout_elements.md) by listening to an event.
An Element might emit any of the events below.
All events have a payload object that has an `elementType` property with the type of the `Element` that emitted the event.

Use the `.on` method on the Element instance to listen to events.

See also: [Elements methods](/js/custom_checkout/custom_checkout_elements.md) | [Listen to Checkout events](/js/custom_checkout/events.md)

## Change event

The change event is triggered when any value in the change event payload changes.
The event payload always contains certain keys, in addition to some `Element`-specific keys.

The following Checkout Elements support the `change` event:
`paymentElement`, `billingAddressElement`, `shippingAddressElement`, and `taxIdElement`.

> Consult with your legal counsel regarding your requirements and obligations about how you collect, use, and store customers' personal data

**Syntax:** `element.on(...)`

#### paymentElement

- `event` ('change') **required**
  The name of the event. In this case, `change`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if all required fields for the selected payment method in the Payment Element
have been filled with potentially valid input.

  - `collapsed` (boolean)
    `true` if the Payment Element is currently collapsed.

  - `value` (object)
    An object containing the current selected PaymentMethod type.

    - `type` (string)
      The type of payment method that was selected.

### Handle a payment element change event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('change', function(event) {
  if (event.complete) {
    // enable payment button
  }
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('change', (event) => {
  if (event.complete) {
    // enable payment button
  }
});
```

#### billingAddressElement

- `event` ('change') **required**
  The name of the event. In this case, `change`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if the value is well-formed and potentially complete.
The `complete` value can be used to progressively disclose the next parts of your form or to enable form submission.

It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value.
In many cases the customer could still add further input.

The `complete` value should not be used to perform an action such as advancing the cursor to a subsequent field or performing a tokenization request.

  - `isNewAddress` (boolean)
    `true` if the Billing Address Element is currently displaying the form collection view.

  - `value` (object)
    An object containing the current address information.

### Handle a billing address element change event

```js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.on('change', function(event) {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

```es_next
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.on('change', (event) => {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

#### shippingAddressElement

- `event` ('change') **required**
  The name of the event. In this case, `change`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if the value is empty.

  - `complete` (boolean)
    `true` if the value is well-formed and potentially complete.
The `complete` value can be used to progressively disclose the next parts of your form or to enable form submission.

It is not an indicator of whether a customer is done with their input—it only indicates that the Element contains a potentially complete, well-formed value.
In many cases the customer could still add further input.

The `complete` value should not be used to perform an action such as advancing the cursor to a subsequent field or performing a tokenization request.

  - `isNewAddress` (boolean)
    `true` if the Shipping Address Element is currently displaying the form collection view.

  - `value` (object)
    An object containing the current address information.

### Handle a shipping address element change event

```js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.on('change', function(event) {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

```es_next
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.on('change', (event) => {
  if (event.complete) {
    // extract potentially complete address
  }
});
```

#### taxIdElement

- `event` ('change') **required**
  The name of the event. In this case, `change`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that
you provide that will be called when the event is fired. When called
it will pass an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `empty` (boolean)
    `true` if both the business name and tax ID fields are empty.

  - `complete` (boolean)
    `true` if all required fields in the Tax ID Element have been filled with potentially valid input.

  - `visible` (boolean)
    `true` if the Tax ID Element is visible based on the `visibility` option and country.

  - `value` (object)
    An object containing the current tax ID information.

The `taxIdType` value corresponds to the selected country-specific type in the Tax ID Element.
The `externalTaxIdType` value corresponds to the tax ID type you would pass to Stripe APIs (for example, EU countries use `eu_vat`).

    - `businessName` (string)
      The business name entered in the Tax ID Element.

    - `taxId` (string)
      The tax ID value entered in the Tax ID Element.

    - `taxIdType` (string)
      The selected tax ID type in the Tax ID Element (for example, `de_vat`).

    - `externalTaxIdType` (string)
      The tax ID type that corresponds to Stripe API values (for example, `eu_vat`).

### Handle a tax ID element change event

```js
const taxIdElement = checkout.createTaxIdElement();
taxIdElement.on('change', function(event) {
  if (event.complete) {
    // Read tax ID details from event.value
  }
});
```

```es_next
const taxIdElement = checkout.createTaxIdElement();
taxIdElement.on('change', (event) => {
  if (event.complete) {
    // Read tax ID details from event.value
  }
});
```

## Ready event

Triggered when the `Element` is fully rendered and methods on the instance, like `element.focus()` and `element.update()`, can be called.

**Syntax:** `element.on(...)`

- `event` ('ready') **required**
  The name of the event.
In this case, `ready`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

After it's called, it passes an event object with the following properties:

  - `elementType` (string) **required**
    The type of element the event is fired from.

### Handle an Element ready event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('ready', function(event) {
  // Handle ready event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('ready', (event) => {
  // Handle ready event
});
```

## Focus event

Triggered when the `Element` gains focus.

**Syntax:** `element.on(...)`

- `event` ('focus') **required**
  The name of the event.
In this case, `focus`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element focus event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('focus', function(event) {
  // Handle focus event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('focus', (event) => {
  // Handle focus event
});
```

## Blur event

Triggered when the `Element` loses focus.

**Syntax:** `element.on(...)`

- `event` ('blur') **required**
  The name of the event.
In this case, `blur`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element blur event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('blur', function(event) {
  // Handle blur event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('blur', (event) => {
  // Handle blur event
});
```

## Escape event

Triggered when the escape key is pressed within an `Element`.

**Syntax:** `element.on(...)`

- `event` ('escape') **required**
  The name of the event.
In this case, `escape`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

### Handle an Element escape event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('escape', function(event) {
  // Handle escape event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('escape', (event) => {
  // Handle escape event
});
```

## LoadError event

Triggered when the `Element` fails to load.

**Syntax:** `element.on(...)`

- `event` ('loaderror') **required**
  The name of the event.
In this case, `loaderror`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

When called it will be passed an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

  - `error` (object)
    An `error` object that describes the failure.

### Handle an Element loaderror event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderror', function(event) {
  // Handle loaderror event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderror', (event) => {
  // Handle loaderror event
});
```

## LoaderStart event

Triggered when the loader UI is mounted to the DOM and ready to be displayed.

See also: [Elements methods](/js/custom_checkout/custom_checkout_elements.md) | [Listen to Elements events](/js/custom_checkout/element_events.md)

**Syntax:** `element.on(...)`

- `event` ('loaderstart') **required**
  The name of the event.
In this case, `loaderstart`.

- `handler` (function) **required**
  `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired.

When called it will be passed an event object with the following properties:

  - `elementType` (string)
    The type of element that emitted this event.

### Handle a Checkout Element loaderstart event

```js
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderstart', function(event) {
  // Handle loaderstart event
});
```

```es_next
const paymentElement = checkout.createPaymentElement();
paymentElement.on('loaderstart', (event) => {
  // Handle loaderstart event
});
```

## Confirm event

The `confirm` event is triggered from the Express Checkout Element when the customer
finalizes their payment. Use this event to trigger payment confirmation.

This event is only available on the Express Checkout Element.

**Syntax:** `expressCheckoutElement.on(...)`

- `event` (string) **required**
  The name of the event.
In this case, `confirm`.

- `handler` (function) **required**
  A callback function `handler(event) => void` you provide that's
called after the event is fired. When called, it passes an event object
with the following properties:

  - `elementType` ('expressCheckout') **required**
    The type of element the event fires from, which is `expressCheckout` in this case.

  - `expressPaymentType` ('apple_pay' | 'google_pay' | 'amazon_pay' | 'paypal' | 'link' | 'klarna') **required**
    The payment method the customer checks out with.

  - `paymentFailed` (function) **required**
    A function `paymentFailed(payload) => void` that's called if you're unable
to process the customer's payment.

    - `reason` ('fail' | 'invalid_shipping_address' | 'invalid_billing_address' | 'invalid_payment_data' | 'address_unserviceable')
      Default is `'fail'`. The payment interface might surface the reason
to provide a hint to the customer on why their payment failed.

    - `message` (string)
      A short, concise, localized error message to display on the payment sheet.
If none is provided, the payment sheet will display a generic error message for the given reason.

  - `billingDetails` (object)
    Object containing information about the customer's billing details.

    - `name` (string)
      The name of the customer.

    - `email` (string)
      The email address of the customer.

    - `phone` (string)
      The phone number of the customer.

    - `address` (object)
      The billing address of the customer.

  - `shippingAddress` (object)
    Object containing information about the customer's shipping address.

    - `name` (string)
      The name of the recipient.

    - `address` (object)
      The shipping address of the customer.

  - `shippingRate` (object)
    Object containing information about the selected shipping rate.

### Handle 'confirm' event

```js
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('confirm', function(event) {
  // call actions.confirm() to confirm the payment
  actions.confirm().then(function(result) {
    if (result.type === 'error') {
      // Inform the customer that there's an error.
    }
  });
});
```

```es_next
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('confirm', async (event) => {
  // call actions.confirm() to confirm the payment
  const result = await actions.confirm();
  if (result.type === 'error') {
    // Inform the customer that there's an error.
  }
});
```

## Cancel event

The `cancel` event is triggered from the Express Checkout Element when the payment interface is dismissed.

Note that in some browsers, the payment interface might be dismissed by the customer even after they authorize the payment.
This means that you might receive a `cancel` event after receiving a `confirm` event.
If you're using the `cancel` event as a hook for canceling the customer's order, make sure you also refund the payment that you just created.

This event is only available on the Express Checkout Element.

**Syntax:** `expressCheckoutElement.on(...)`

- `event` (string) **required**
  The name of the event.
In this case, `cancel`.

- `handler` (function) **required**
  A callback function that you provide that's called after the event is fired.

### Handle 'cancel' event

```js
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('cancel', function() {
  // handle cancel event
});
```

```es_next
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.on('cancel', () => {
  // handle cancel event
});
```