Skip to main content

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
}
});
ParameterRequiredTypeDescription
eventtrue"change"The event type to listen to.
handlertruefunctionCallback 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"
}
AttributeTypeEligible ElementsDescription
completebooleanAllWhether the input valid and maskSatisfied properties are true.
validbooleanAllWhether the input is valid according to validation for each element. Defaults to true if no validation is defined for the element.
maskSatisfiedbooleanAllWhether the input satisfies the mask length requirements. Defaults to true if no mask is provided.
emptybooleanAllWhether the element is empty. Multi-input Elements will be empty only if all inputs are.
errorsarrayAllArray of FieldError.
cardBrandstringcard
cardNumber
(Optional) The credit card brand (e.g., 'american-express', 'visa', 'unknown'). The value defaults to 'unknown' until a card brand is recognized.
cardLast4stringcard
cardNumber
(Optional) The credit card's last 4 digits. The value is not provided until a complete card number is entered.
cardBinstringcard
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.

AttributeEligible ElementsAttributes
metadataAllcomplete, valid, maskSatisfied, empty
cardMetadatacard
cardNumber
cardLast4, cardBin, cardBrand

FieldError

{
"targetId": "cardNumber",
"type": "invalid"
}
AttributeTypeDescription
targetIdstringInput 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
});
ParameterRequiredTypeDescription
eventtrue"focus"The event type to listen to.
handlertruefunctionCallback function to be called when the event is fired. Takes in a FocusEvent.

FocusEvent

{
"targetId": "cardNumber"
}
AttributeTypeDescription
targetIdstringInput 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
});
ParameterRequiredTypeDescription
eventtrue"blur"The event type to listen to.
handlertruefunctionCallback function to be called when the event is fired. Takes in a BlurEvent.

BlurEvent

{
"targetId": "cardNumber"
}
AttributeTypeDescription
targetIdstringInput 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
});
ParameterRequiredTypeDescription
eventtrue"keydown"The event type to listen to.
handlertruefunctionCallback 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
}
AttributeTypeDescription
targetIdstringInput targetId that triggered the event. Values vary per element type.
keyEscape or EnterKey pressed by the user.
ctrlKeybooleanFlag indicating control key was pressed when the event occurred.
altKeybooleanFlag indicating alt key was pressed when the event occurred.
shiftKeybooleanFlag indicating shift key was pressed when the event occurred.
metaKeybooleanFlag indicating meta key was pressed when the event occurred.