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

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Element object - Elements SDK

> Reference for a single mounted card field (Element): mount and unmount it, listen to its events, and read its field state.

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

## Methods

<ResponseField name="type" type="ElementType" required>
  The Element type this instance renders.
</ResponseField>

### `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.

<ResponseField name="target" type="string | HTMLElement" required>
  A CSS selector or the container element.
</ResponseField>

**Throws:**

* [`element:destroyed`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`load_error`) — the Element was destroyed.
* [`element:container_not_found`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`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.

<ResponseField name="event" type="K" required>
  Event name. See `ElementEventMap` for payloads.
</ResponseField>

<ResponseField name="handler" type="(e: ElementEventMap[K]) => void" required>
  Called with the event payload.
</ResponseField>

### `off(event, handler)`

Remove a handler previously added with `Element.on`.

<ResponseField name="event" type="K" required>
  Event name.
</ResponseField>

<ResponseField name="handler" type="(e: ElementEventMap[K]) => void" required>
  The same function reference passed to `on()`.
</ResponseField>

### `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`.

<ResponseField name="options" type="{ appearance?: AppearanceOptions; }" required>
  `appearance` to apply. Calls without `appearance` are ignored.
</ResponseField>

### `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

<ResponseField name="ready" type="ReadyEvent">
  Payload of the `ready` event — emitted once the iframe has loaded and the field accepts input.

  Emitted again after each re-`mount()`.

  <Expandable title="ReadyEvent properties" defaultOpen>
    <ResponseField name="elementType" type="ElementType" required>
      The Element that became ready.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="change" type="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.

  <Expandable title="ChangeEvent properties" defaultOpen>
    <ResponseField name="brand" type="CardBrand">
      Detected card brand. Present on `'card'` and `'cardNumber'` Elements only. `'cardNumber'` omits it while the brand is unknown; `'card'` may report `'unknown'`.
    </ResponseField>

    <ResponseField name="complete" type="boolean" required>
      `true` when the field holds a full, acceptable value. Currently always equal to `valid` — see the `ChangeEvent` remarks.
    </ResponseField>

    <ResponseField name="elementType" type="ElementType" required>
      The Element that changed.
    </ResponseField>

    <ResponseField name="empty" type="boolean" required>
      `true` when the field (every cell, for `'card'`) has no input.
    </ResponseField>

    <ResponseField name="error" type="FieldError | null" required>
      The current validation error, or `null`. Set by blur-time validation; see `FieldErrorCode` for the possible codes.

      <Expandable title="FieldError properties">
        <ResponseField name="code" type="FieldErrorCode" required>
          Machine-readable error code. Branch on this, not on `message`.
        </ResponseField>

        <ResponseField name="field" type="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.
        </ResponseField>

        <ResponseField name="message" type="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.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="valid" type="boolean" required>
      `true` when the field passes all validation. Use this to enable submit.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="focus" type="FocusEvent">
  Payload of the `focus` event — emitted when the field receives focus.

  <Expandable title="FocusEvent properties" defaultOpen>
    <ResponseField name="elementType" type="ElementType" required>
      The Element that received focus.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="blur" type="BlurEvent">
  Payload of the `blur` event — emitted when the field loses focus.

  <Expandable title="BlurEvent properties" defaultOpen>
    <ResponseField name="elementType" type="ElementType" required>
      The Element that lost focus.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cardTypeChange" type="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).

  <Expandable title="CardTypeChangeEvent properties" defaultOpen>
    <ResponseField name="binLength" type="number" required>
      Number of card-number digits entered when the brand changed, capped at 8.
    </ResponseField>

    <ResponseField name="brand" type="CardBrand" required>
      The newly detected brand (`'unknown'` when no brand matches).
    </ResponseField>
  </Expandable>
</ResponseField>

### 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

<Tabs>
  <Tab title="Vanilla JS">
    ```js theme={null}
    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());
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={null}
    import { CardElement } from "@cubepay/react-radiumone-js";

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

See [Card fields and events](/elements/card-fields-and-events) for element types, create options, and Safari notes.

## Errors

See [Elements SDK errors](/elements/errors/error-object-and-handling).