Card fields

Overview

Elements is the set of secure card fields for one payment. You create it from your publishable key, scoped to a single intent by its client_secret, so every field you render belongs to that one intent.

const modulus = new Modulus('pk_test_...');

const elements = modulus.elements({
  paymentIntentId: 'b7e2c1a4-9f3d-4c6b-8a21-5e0f7d9c3b18',
  clientSecret: '3f9a6d2e-7c14-4b8f-a5d0-1e6c2b9f4a73',
  appearance: { variables: { colorPrimary: '#1e88e5', borderRadius: '8px' } },
});

`elements(options)`	Type	Notes
`paymentIntentId`	string	Required. The intent `id`.
`clientSecret`	string	Required. The intent `client_secret`.
`appearance`	object	Customize the look of the fields. See Appearance.
`loader`	string	Controls the shimmer skeleton shown in each field while it boots, cleared once the field is ready. `'auto'` (default) and `'always'` show it; `'never'` hides it.
`disableAnimations`	boolean	Turns off the fields’ mount and focus transitions. Set `true` for an instant, motion-free render.

Create and mount fields

create instantiates one field as a secure Modulus iframe. mount inserts that iframe into a placeholder element on your page, by CSS selector or DOM node. The customer types into the iframe, and your page cannot read its contents.

const cardNumber = elements.create('cardNumber', { placeholder: '1234 1234 1234 1234' });
cardNumber.mount('#card-number');

elements.create('cardExpiry').mount('#card-expiry');
elements.create('cardCvc').mount('#card-cvc');

Use split fields (number / expiry / cvc) or a single combined 'card' field.

Choose one model. Do not mix a split cardNumber field with the combined card field in the same form.

Field types

Field type	Renders
`'cardNumber'`	Card number input, with brand detection.
`'cardExpiry'`	Expiry (MM / YY).
`'cardCvc'`	Security code.
`'cardholderName'`	Name on card. A secure field, separate from the `billingDetails` name you pass to `confirmPayment`.
`'card'`	All-in-one combined field (number + expiry + cvc).

create() options

Option	Type	What it does
`placeholder`	string	Grey hint text shown in the empty field (split fields).
`placeholders`	object	Per-part hints for the combined `card` field: `{ number, expiry, cvc }`.
`label`	string	Accessible label for the field (screen readers).
`disabled`	boolean	Renders the field read-only.
`style`	object	Per-field style overrides, the properties below, on top of the group Appearance.

style properties

Property	Example	Property	Example
`color`	`'#0A0A0F'`	`letterSpacing`	`'0.5px'`
`fontFamily`	`'Inter, sans-serif'`	`lineHeight`	`'1.5'`
`fontSize`	`'16px'`	`textAlign`	`'left'`
`fontWeight`	`'400'`	`textDecoration`	`'none'`
`fontStyle`	`'normal'`	`textTransform`	`'none'`
`padding`	`'10px 12px'`	`backgroundColor`	`'#FFFFFF'`

Appearance

Style every field in the group at once with an appearance.variables object passed to elements(). Per-field style overrides (above) layer on top of these.

const elements = modulus.elements({
  paymentIntentId,
  clientSecret,
  appearance: {
    variables: {
      colorPrimary: '#1e88e5',
      colorText: '#0f2a2c',
      colorDanger: '#d94a4a',
      colorBackground: '#ffffff',
      fontFamily: 'Inter, sans-serif',
      fontSize: '15px',
      borderRadius: '8px',
      borderColor: '#d9dee3',
    },
  },
});

Variable	Controls
`colorPrimary`	Accent, the focus ring and active border.
`colorText`	Typed input text colour.
`colorTextSecondary`	Placeholder and secondary text.
`colorDanger`	Error text and invalid-field border.
`colorBackground`	Field background.
`fontFamily`	Font for the input text.
`fontFamilyMono`	Monospace font (card number digits).
`fontSize`	Input font size.
`borderRadius`	Corner rounding of the fields.
`borderColor`	Default field border colour.

Element methods

Method	What it does
`mount(target)`	Inserts this field’s secure iframe into a placeholder in your DOM, a `<div>` you point at by CSS selector or DOM node. The iframe is served from the Modulus domain, so the typed card characters live inside it and your page’s JavaScript cannot read them.
`unmount()`	Removes the field’s iframe from the page, for example when leaving checkout.
`retry()`	Re-attempts loading a field that failed, after a `loaderror`.
`on(event, handler)`	Subscribe to field events. See below.
`off(event, handler)`	Remove a previously added field event handler.

Group methods

The Elements group exposes methods for driving your form and cleanup:

Method	What it does
`on(event, handler)`	Subscribe to group events, for example `change`.
`off(event, handler)`	Remove a group event handler.
`isComplete()`	Returns `true` when every mounted field is valid and filled.
`destroy()`	Unmounts and tears down all fields in the group.

Field events

Subscribe per field with element.on(...), or once on the whole group with elements.on('change'). The group listener is the easy way to drive your Pay button.

// Per-field events
cardNumber.on('ready', () => {});          // iframe loaded and secure, ok to type
cardNumber.on('change', (e) => {
  // e.complete -> this field is valid and fully filled
  // e.empty    -> the field currently has no input
  // e.error    -> { message } if the current input is invalid
  // e.brand    -> 'visa' | 'mastercard' | ... (card-number field)
});
cardNumber.on('focus', () => {});          // field gained focus
cardNumber.on('blur', () => {});           // field lost focus
cardNumber.on('loaderror', (e) => {
  // e.elementType -> 'cardNumber' | 'cardExpiry' | ...
  // e.error       -> { code, message }
  showReload(e.error.message);
});

// Whole-form completeness, gate the Pay button on ALL fields
elements.on('change', (e) => {
  // e.complete -> every mounted field is valid and filled
  // e.fields   -> per-field state, keyed by element type
  payButton.disabled = !e.complete;
});

The group change fires on every keystroke in any field. Its complete is true only when every mounted field is valid and filled, so gating on it keeps Pay disabled until the whole card form is ready, then enables it.

A field fires loaderror when its secure iframe cannot come up, for example the customer’s network dropped mid-load, an ad-blocker or corporate proxy blocked the Modulus domain, or the secure-channel handshake timed out after the SDK’s own retries. Surface a reload affordance and call element.retry().

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Create and mount fields

Field types

create() options

style properties

Appearance

Element methods

Group methods

Field events

​Overview

​Create and mount fields

​Field types

​create() options

​style properties

​Appearance

​Element methods

​Group methods

​Field events

Overview

Create and mount fields

Field types

create() options

style properties

Appearance

Element methods

Group methods

Field events