> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Card fields
> Create, mount, style, and listen to the secure card Elements
## 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.
```javascript theme={null}
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](#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.
```javascript theme={null}
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](#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.
```javascript theme={null}
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 `` 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.
```javascript theme={null}
// 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()`.