Card reference

Factory

overflow.card(options?: CardElementOptions): CardElement

Options

All keys are optional.

Key	Type	Default	Description
`disabled`	`boolean`	`false`	Disables every input inside the element. Does not affect the secured iframe fields visually beyond the DOM `disabled` attribute; use unmount to fully suppress input.
`readOnly`	`boolean`	`false`	Cascades to native inputs (`holderName`, `postalCode`). Ignored on the secured iframe fields.
`id`	`string`	auto	DOM id on the host wrapper.
`ariaLabel`	`string`	none	Sets `aria-label` and `role="group"` on the host wrapper when supplied.
`locale`	`string`	Overflow instance locale	BCP-47 locale for field labels.
`fieldLayout`	`'stacked' \| 'inline'`	`'stacked'`	Layout for the secured fields. `'inline'` renders card number, expiration, and security code on one row where space allows.
`fields`	see below	`{}`	Per-input customization.

card does not accept required or validate. Every visible card field is always required and validation is built in. Suppress optional atoms with fields.holderName.hidden, fields.postalCode.hidden, or fields.cardSecurityCode.hidden instead.

`fields`

`cardNumber` (secured iframe)

Key	Type	Default
`label`	`string`	`'Card number'`
`placeholder`	`string`	none
`iconStyle`	`'default' \| 'solid'`	`'default'`

disabled, hidden, autoFocus, id, ariaLabel are intentionally not exposed on this field: the secured iframe does not honor them.

`cardExpiration` (secured iframe)

Key	Type	Default
`label`	`string`	`'Expiration'`
`placeholder`	`string`	`'MM / YY'`

`cardSecurityCode` (secured iframe)

Key	Type	Default
`label`	`string`	`'Security code'`
`placeholder`	`string`	none
`hidden`	`boolean`	`false`

Hide the security code only for card programs that do not require CVC (for example, some private-label or corporate cards). Hiding it removes the field from validation.

`holderName` (native input)

Key	Type	Default
`label`	`string`	`'Name on card'`
`placeholder`	`string`	none
`disabled`	`boolean`	inherits element `disabled`
`hidden`	`boolean`	`false`
`id`	`string`	auto
`ariaLabel`	`string`	none

autoFocus is not supported. The secured card-number iframe grabs initial focus.

`postalCode` (native input)

Same shape as holderName. Default label 'Postal code'.

Value

The card element emits an encrypted value envelope on onSubmit. Raw card data never leaves the secured iframes; every sensitive field is encrypted before it reaches your handler.

type CardElementValue = {
  encryptedCardNumber: string;
  encryptedExpiryMonth: string;
  encryptedExpiryYear: string;
  encryptedSecurityCode: string;
  riskData: { clientData: string };
  browserInfo: {
    acceptHeader: string;
    colorDepth: number;
    language: string;
    javaEnabled: boolean;
    screenHeight: number;
    screenWidth: number;
    timeZoneOffset: number;
    userAgent: string;
  };
  holderName?: string;
  postalCode?: string;
};

Forward the full envelope to your server verbatim; do not try to unpack or transform the encrypted* fields. holderName and postalCode are present only when the corresponding field is visible and non-empty. encryptedSecurityCode is present only when fields.cardSecurityCode.hidden is not set.

Events

Every element event is supported: onReady, onChange, onSubmit, onError, onFocus, onBlur, onEscapeKeyPressed. See Events overview.

`FieldError.field` values

'cardNumber', 'expiryDate', 'cvc', 'holderName', 'postalCode'.

Methods

card.mount(selector)
card.update(partialOptions)
card.submit()
card.unmount()
card.destroy()
card.on(event, handler)

Get started

Elements

Options

Events

Theming

Guides

Factory

Options

`fields`

`cardNumber` (secured iframe)

`cardExpiration` (secured iframe)

`cardSecurityCode` (secured iframe)

`holderName` (native input)

`postalCode` (native input)

Value

Events

`FieldError.field` values

Methods

​Factory

​Options

​fields

​cardNumber (secured iframe)

​cardExpiration (secured iframe)

​cardSecurityCode (secured iframe)

​holderName (native input)

​postalCode (native input)

​Value

​Events

​FieldError.field values

​Methods

Factory

Options

`fields`

`cardNumber` (secured iframe)

`cardExpiration` (secured iframe)

`cardSecurityCode` (secured iframe)

`holderName` (native input)

`postalCode` (native input)

Value

Events

`FieldError.field` values

Methods