Element object - Elements SDK

Element represents one mounted card field (combined card, or one of the split types). Get one from elements.create(type, options?).

Methods

ElementType

required

The Element type this instance renders.

`mount(target)`

Insert the Element’s iframe into a container on the page. Requires HTTPS outside localhost. Calling mount() on an already-mounted Element logs a warning and does nothing. The Element destroys itself when its container is removed from the DOM and when the page unloads. Emits ready once the iframe has loaded; if it has not loaded within 5 seconds a change event with error.code === 'required' is emitted.

string | HTMLElement

required

A CSS selector or the container element.

Throws:

element:destroyed (load_error) — the Element was destroyed.
element:container_not_found (load_error) — no element matches target.

`unmount()`

Remove the iframe from the page. The Element keeps its event handlers and can be mounted again. Does nothing if not mounted.

`destroy()`

Unmount and permanently release the Element: removes all event handlers and frees its type so Elements.create can create it again. Idempotent.

`on(event, handler)`

Subscribe to an Element event.

required

Event name. See ElementEventMap for payloads.

(e: ElementEventMap[K]) => void

required

Called with the event payload.

`off(event, handler)`

Remove a handler previously added with Element.on.

required

Event name.

(e: ElementEventMap[K]) => void

required

The same function reference passed to on().

`focus()`

Move focus into the field. Does nothing if not mounted.

`blur()`

Remove focus from the field. Does nothing if not mounted.

`clear()`

Clear the field’s input and emit change. On the combined 'card' Element only the card number is cleared.

`update(options)`

Restyle this Element only. To restyle every Element, use Elements.update. The appearance is sanitized with the same rules as AppearanceOptions. Safe to call before the iframe is ready — the latest value is applied on ready.

{ appearance?: AppearanceOptions; }

required

appearance to apply. Calls without appearance are ignored.

`getState()`

The field state as of the most recent change event. Synchronous and cached. For a live read of every field, use Elements.getState. Returns FieldState — A copy of the cached FieldState.

Events

ReadyEvent

Payload of the ready event — emitted once the iframe has loaded and the field accepts input.Emitted again after each re-mount().

Hide ReadyEvent properties

ElementType

required

The Element that became ready.

ChangeEvent

Payload of the change event — emitted when a field’s value, completion or validity changes.Fired on input, paste, deletion and clear(). Also fired with error.code === 'required' if the iframe fails to load within 5 seconds (for example when a browser extension blocks it), and once more with error: null if it loads later.complete vs valid. For every Element type the two flags are currently always equal: a field only becomes complete once its content passes validation. - Card number: a valid length for the detected brand and a passing Luhn checksum, and — when CreateElementOptions.supportedBrands is set — a recognised brand must be in that list. - Expiry: four digits forming a month 01–12, not in the past, and at most 12 years ahead. - CVV: the full length for the detected brand (4 for Amex, 3 otherwise). - Combined 'card': every visible cell is complete and valid.Gate your pay button on valid.error is produced by blur-time validation, so it can be null while valid is false (the shopper is still typing). Use error for messaging, not for gating.

Hide ChangeEvent properties

CardBrand

Detected card brand. Present on 'card' and 'cardNumber' Elements only. 'cardNumber' omits it while the brand is unknown; 'card' may report 'unknown'.

boolean

required

true when the field holds a full, acceptable value. Currently always equal to valid — see the ChangeEvent remarks.

ElementType

required

The Element that changed.

boolean

required

true when the field (every cell, for 'card') has no input.

FieldError | null

required

The current validation error, or null. Set by blur-time validation; see FieldErrorCode for the possible codes.

Show FieldError properties

FieldErrorCode

required

Machine-readable error code. Branch on this, not on message.

string

required

The ElementType the error belongs to (for example 'cardExpiry'). On the combined 'card' Element this is always 'card'; use code to tell which cell failed.

string

required

Shopper-facing message, safe to display. Field validation messages follow the Elements locale; required errors from Elements.getState and Elements.submit, and the load-timeout message, are English.

boolean

required

true when the field passes all validation. Use this to enable submit.

FocusEvent

Payload of the focus event — emitted when the field receives focus.

Hide FocusEvent properties

ElementType

required

The Element that received focus.

BlurEvent

Payload of the blur event — emitted when the field loses focus.

Hide BlurEvent properties

ElementType

required

The Element that lost focus.

CardTypeChangeEvent

Payload of the cardTypeChange event — emitted when the detected card brand changes as the shopper types the card number.Emitted by 'card' and 'cardNumber' Elements only, and only when the brand actually changes (not on every keystroke).

Hide CardTypeChangeEvent properties

number

required

Number of card-number digits entered when the brand changed, capped at 8.

CardBrand

required

The newly detected brand ('unknown' when no brand matches).

Element events

Event	Element types	React prop	When
`ready`	`card`, `cardNumber`, `cardExpiry`, `cardCvv`	`onReady`	The iframe has loaded and accepts input. Emitted again after each re-mount.
`change`	`card`, `cardNumber`, `cardExpiry`, `cardCvv`	`onChange`	Value, completion or validity changed (input, paste, deletion, clear()). Also emitted with error.code ‘required’ when the iframe has not loaded within 5 seconds, and with error null if it loads later.
`focus`	`card`, `cardNumber`, `cardExpiry`, `cardCvv`	`onFocus`	The field received focus.
`blur`	`card`, `cardNumber`, `cardExpiry`, `cardCvv`	`onBlur`	The field lost focus. Blur runs field validation, so ChangeEvent.error is updated from the next change.
`cardTypeChange`	`card`, `cardNumber`	`onCardTypeChange`	The detected card brand changed while typing the card number. Not emitted on every keystroke.

`FieldErrorCode` values

Code	Meaning
`required`	The field is empty (also used when the field failed to load).
`incomplete_number`	Card number length is not valid for the detected brand.
`invalid_number`	Card number fails the Luhn checksum.
`unsupported_brand`	Detected brand is not in CreateElementOptions.supportedBrands.
`incomplete_expiry`	Expiry has fewer than four digits.
`invalid_month`	Expiry month is outside 01-12.
`invalid_year`	Expiry year is more than 12 years ahead.
`expired_card`	Expiry date is in the past.
`invalid_expiry`	Generic expiry fallback; not raised by the current iframe.
`incomplete_cvv`	CVV is shorter than required for the detected brand.
`invalid_cvv`	CVV length does not match the detected brand.

Example

Vanilla JS
React

const card = elements.create("card");
card.mount("#card-field");

card.on("change", (event) => {
  payButton.disabled = !event.valid;
  if (event.error) showFieldError(event.error.message);
});

card.on("ready", () => hideLoadingSpinner());

import { CardElement } from "@cubepay/react-radiumone-js";

<CardElement
  onChange={(e) => setReady(e.valid)}
  onReady={() => setLoading(false)}
/>

See Card fields and events for element types, create options, and Safari notes.

Errors

See Elements SDK errors.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Element object - Elements SDK

Methods

`mount(target)`

`unmount()`

`destroy()`

`on(event, handler)`

`off(event, handler)`

`focus()`

`blur()`

`clear()`

`update(options)`

`getState()`

Events

Element events

`FieldErrorCode` values

Example

Errors

​Methods

​mount(target)

​unmount()

​destroy()

​on(event, handler)

​off(event, handler)

​focus()

​blur()

​clear()

​update(options)

​getState()

​Events

​Element events

​FieldErrorCode values

​Example

​Errors

Methods

`mount(target)`

`unmount()`

`destroy()`

`on(event, handler)`

`off(event, handler)`

`focus()`

`blur()`

`clear()`

`update(options)`

`getState()`

Events

Element events

`FieldErrorCode` values

Example

Errors