Events

You can communicate with Elements by listening to events. When you subscribe to an event, you'll get back a Subscription that you can unsubscribe if/when it fits your workflow.

var cardElementRef = useRef(null);

<CardElement
  id="cardElement"
  ref={cardElementRef}
/>

// Make sure to replace 'event-type' with an actual event type.
var subscription = cardElementRef.current.on("event-type", (event) => {
  // handle event
});

subscription.unsubscribe(); // stops listening to the event type

On Ready

This event is triggered when the element has rendered and user is able to start interacting with it.

// adding listener on creation
<CardElement
  id="cardElement"
  onReady={() => {
    // handle ready event
  }}
/>

// using refs
cardElementRef.current.on("ready", () => {
  // handle ready event
});

On Change

This event is triggered whenever element's value(s) change. For example, if the user types data that doesn't change the state of a field between valid/invalid or empty/filled, you shouldn't expect the event to trigger.

// adding listener on creation
<CardElement
  id="cardElement"
  onChange={(changeEvent) => {
    if (changeEvent.complete) {
      // enable submit button
    } else {
      // disable submit button
      // present validation message
    }
  }}
/>

// or using refs
cardElementRef.current.on("change", (changeEvent) => {
      if (changeEvent.complete) {
      // enable submit button
    } else {
      // disable submit button
      // present validation message
    }
});

Parameter	Required	Type	Description
event	true	"change"	The event type to listen to.
handler	true	function	Callback function to be called when the event is fired. Takes in a ChangeEvent.

ChangeEvent

ChangeEvents are emitted depending on the validation strategy set for each element; by default, validations run onBlur. You can change this behavior by setting the boolean flag validateOnChange to true.

When running validations onChange, elements emit events whenever an error occurs or if the input's value changes. Default validation (onBlur) triggers an event every time one of the values below changes:

{
  "complete": false,
  "valid": false,
  "maskSatisfid": false,
  "empty": false,
  "errors": [
    {...},
    {...}
  ],
  "cardBrand": "american-express",
  "cardLast4": "8431",
  "cardBin": "341212"
}

Attribute	Type	Eligible Elements	Description
complete	boolean	All	Whether the input valid and maskSatisfied properties are true.
valid	boolean	All	Whether the input is valid according to validation for each element. Defaults to true if no validation is defined for the element.
maskSatisfied	boolean	All	Whether the input satisfies the mask length requirements. Defaults to true if no mask is provided.
empty	boolean	All	Whether the element is empty. Multi-input Elements will be empty only if all inputs are.
errors	array	All	Array of FieldError.
cardBrand	string	card cardNumber	(Optional) The credit card brand (e.g., 'american-express', 'visa', 'unknown'). The value defaults to 'unknown' until a card brand is recognized.
cardLast4	string	card cardNumber	(Optional) The credit card's last 4 digits. The value is not provided until a complete card number is entered.
cardBin	string	card cardNumber	(Optional) The credit card number's first 6 or 8 digits when the input is considered complete. It is 6 digits for card numbers less than 16 digit long and 8 otherwise.

Metadata

Instead of subscribing to events, the same properties can be accessed at any time from the metadata property on all elements.

Additionally, the card related event change events can be accessed from the cardMetadata property only on Card and CardNumber elements.

Attribute	Eligible Elements	Attributes
metadata	All	complete, valid, maskSatisfied, empty, errors
cardMetadata	card cardNumber	cardLast4, cardBin, cardBrand

FieldError

{
  "targetId": "cardNumber",
  "type": "invalid"
}

Attribute	Type	Description
targetId	string	Input ID that triggered the error. Values vary per element type.
type	"invalid" or "incomplete"	Type of the error.

On Focus

Triggered when an element input is focused.

// adding listener on creation
<CardElement
  id="cardElement"
  onFocus={(focusEvent) => {
    // handle focus event
  }}
/>

// using refs
cardElementRef.current.on("focus", (focusEvent) => {
  // handle focus event
});

Parameter	Required	Type	Description
event	true	"focus"	The event type to listen to.
handler	true	function	Callback function to be called when the event is fired. Takes in a FocusEvent.

FocusEvent

{
  "targetId": "cardNumber"
}

Attribute	Type	Description
targetId	string	Input ID that triggered the event. Values vary per element type.

On Blur

Triggered when an element input focus is lost.

// adding listener on creation
<CardElement
  id="cardElement"
  onBlur={(blurEvent) => {
    // handle blur event
  }}
/>

// using refs
cardElementRef.current.on("blur", (blurEvent) => {
  // handle blur event
});

Parameter	Required	Type	Description
event	true	"blur"	The event type to listen to.
handler	true	function	Callback function to be called when the event is fired. Takes in a BlurEvent.

BlurEvent

{
  "targetId": "cardNumber"
}

Attribute	Type	Description
targetId	string	Input ID that triggered the event. Values vary per element type.

On Keydown

Triggered when user hits a special key inside an element input.

// adding listener on creation
<CardElement
  id="cardElement"
  onKeyDown={(keydownEvent) => {
    // handle keydown event
  }}
/>

// using refs
cardElementRef.current.on("keydown", (keydownEvent) => {
  // handle keydown event
});

Parameter	Required	Type	Description
event	true	"keydown"	The event type to listen to.
handler	true	function	Callback function to be called when the event is fired. Takes in a KeydownEvent.

KeydownEvent

{
  "targetId": "cardNumber",
  "key": "Enter",
  "ctrlKey": false,
  "altKey": false,
  "shiftKey": false,
  "metaKey": false
}

Attribute	Type	Description
targetId	string	Input targetId that triggered the event. Values vary per element type.
key	Escape or Enter	Key pressed by the user.
ctrlKey	boolean	Flag indicating control key was pressed when the event occurred.
altKey	boolean	Flag indicating alt key was pressed when the event occurred.
shiftKey	boolean	Flag indicating shift key was pressed when the event occurred.
metaKey	boolean	Flag indicating meta key was pressed when the event occurred.