Events

ElementEvent

iOS Element events are triggered whenever a user types into an element text field. An ElementEvent is the struct that gets passed into the subject's receiveValue function. The following are properties on the ElementEvent struct:

Property	Description
type	The event type for the ElementEvent.
complete	Whether the input valid and maskSatisfied properties are true.
valid	Whether the input is valid according to validation for each element.
maskSatisfied	Whether the input satisfies the mask length requirements.
details	An array of ElementEventDetail describing more information about the element event.
binInfo	BinInfo object containing card BIN details when binLookup is enabled on CardNumberUITextField.
selectedNetwork	The selected payment network for co-badged cards (e.g., "cartes-bancaires", "visa"). Only present when co-badge support is enabled.

ElementEvent Types

The following are the available element event types and their descriptions.

Type	Description
textChange	All elements emit this event when a user changes an element's value.
focus	All elements emit this event on textFieldDidBeginEditing.
blur	All elements emit this event on textFieldDidEndEditing.
maskChange	CardVerificationCodeUITextField elements emit this event when its mask has changed.
copy	Elements with enableCopy set to true emit this event when the value is copied to the clipboard via the copy button. Available on TextElementUITextField, CardNumberUITextField, CardExpirationDateUITextField, and CardVerificationCodeUITextField.

ElementEventDetail

Property	Description
type	A String describing the type of detail.
message	A String containing the message for the detail.

ElementEventDetail Types

The following are the available element event detail types and their descriptions.

Type	Description
cardBrand	CardNumberUITextField elements emit a card brand name when a card number can be identified.
cardLast4	CardNumberUITextField elements emit the last 4 digits of a card number when the input is considered complete.
cardBin	CardNumberUITextField elements emit the first 6 or 8 digits of a card number when the input is considered complete. It is 6 digits for card numbers less than 16 digits long and 8 otherwise.

Usage

You can observe element events through the PassThroughSubject subject field on every element.

private var cancellables = Set<AnyCancellable>()
...

myTextField.subject.sink { completion in
    ...
} receiveValue: { elementEvent in
    ...
}.store(in: &cancellables)

Using Metadata for Event Values

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 details can be accessed from the cardMetadata property only on CardNumberUITextField.

The following are the available properties accessible from metadata.

Property	Type	Description
complete	Bool	Whether the input valid and maskSatisfied properties are true.
valid	Bool	Whether the input is valid according to validation for each element.
maskSatisfied	Bool	Whether the input satisfies the mask length requirements.

The following are the available properties accessible from cardMetadata.

Property	Type	Description
cardBrand	String	Card brand name when a card number can be identified.
cardLast4	String	Last 4 digits of a card number when the input is considered complete.
cardBin	String	First 6 or 8 digits of a card number when the input is considered complete. It is 6 digits for card numbers less than 16 digits long and 8 otherwise.

BinInfo

When binLookup is enabled on a CardNumberUITextField, the element will automatically perform a BIN lookup and include the results in the binInfo property of the ElementEvent. This provides detailed information about the card based on its BIN (Bank Identification Number).

BinInfo Properties

Property	Type	Description
brand	String?	The card brand (e.g., "visa", "mastercard")
funding	String?	The funding type (e.g., "credit", "debit", "prepaid")
issuer	String?	The name of the issuing bank
segment	String?	The card segment type
additional	[CardInfo]?	Array of additional card information for co-badged cards

CardInfo Properties

Property	Type	Description
brand	String?	Additional card brand for co-badged cards
funding	String?	Funding type for the additional brand
issuer	String?	Issuer for the additional brand

Enabling BIN Lookup

To enable BIN lookup on a CardNumberUITextField:

let cardNumberTextField = CardNumberUITextField()
cardNumberTextField.binLookup = true

Usage Example

cardNumberTextField.subject.sink { completion in
} receiveValue: { event in
    if let binInfo = event.binInfo {
        print("Card brand: \(binInfo.brand ?? "unknown")")
        print("Funding type: \(binInfo.funding ?? "unknown")")
        print("Issuer: \(binInfo.issuer ?? "unknown")")
        
        // Check for co-badged cards
        if let additional = binInfo.additional, !additional.isEmpty {
            print("Co-badged card detected")
            additional.forEach { cardInfo in
                print("Additional brand: \(cardInfo.brand ?? "unknown")")
            }
        }
    }
}.store(in: &cancellables)

Copy Event

The copy event is triggered when a value is successfully copied to the clipboard via the copy button. This event is available on elements that have the enableCopy option set to true (TextElementUITextField, CardNumberUITextField, CardExpirationDateUITextField, CardVerificationCodeUITextField).

Enabling Copy

To enable the copy button on an element, use the setConfig method with the appropriate options:

// For TextElementUITextField, CardNumberUITextField and CardExpirationDateUITextField
let cardNumberTextField = CardNumberUITextField()
try? cardNumberTextField.setConfig(options: TextElementOptions(enableCopy: true, copyIconColor: UIColor.blue))

// For CardVerificationCodeUITextField
let cvcTextField = CardVerificationCodeUITextField()
cvcTextField.setConfig(options: CardVerificationCodeOptions(enableCopy: true, copyIconColor: UIColor.blue))

Usage Example

private var cancellables = Set<AnyCancellable>()

// Enable copy on the card number field
let cardNumberTextField = CardNumberUITextField()
try? cardNumberTextField.setConfig(options: TextElementOptions(enableCopy: true))

// Subscribe to events including copy events
cardNumberTextField.subject.sink { completion in
} receiveValue: { event in
    if event.type == "copy" {
        print("Card number copied to clipboard")
        // Show a toast or confirmation to the user
        showCopiedConfirmation()
    }
}.store(in: &cancellables)