> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Card reference

> Full options, fields, and value reference for the card element.

## Factory

```typescript theme={null}
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.

```typescript theme={null}
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](/payment-elements/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)`