Element Methods

Once you have created and mounted an element, you can call these methods to interact with it. All element types share the same interface.

---

Properties

Property	Type	Description
id	string	Unique identifier assigned at creation time
type	'cardNumber' | 'cvv' | 'expiry' | 'text'	The element type
mounted	boolean	true when the element is attached to the DOM

---

Methods

mount(selector)

Attaches the element iframe to the DOM. Must be awaited — the promise resolves when the element is loaded and the ready event has fired.

mount(selector: string | HTMLElement): Promise<void>

await cardNumberEl.mount('#card-number-container');
// element is now interactive

Pass either a CSS selector string or a direct HTMLElement reference.

---

unmount()

Removes the element iframe from the DOM and cleans up all event listeners. Synchronous.

unmount(): void

cardNumberEl.unmount();

---

update(options)

Sends new options to the element iframe. Returns a promise that resolves when the element has applied the update.

update(options: Partial<ElementOptions> & { themeMode?: 'light' | 'dark' | 'auto' }): Promise<void>

await cardNumberEl.update({
  placeholder: 'Enter card number',
  disabled: false,
});

You can also update the theme mode for a single element without affecting others:

await cardNumberEl.update({ themeMode: 'dark' });

See Element Options for the full list of options that can be passed to update().

---

focus()

Programmatically focuses the input inside the element iframe. Synchronous.

focus(): void

cardNumberEl.focus();

---

blur()

Programmatically blurs (removes focus from) the input. Synchronous.

blur(): void

cardNumberEl.blur();

---

clear()

Clears the current input value. Synchronous.

clear(): void

cardNumberEl.clear();

---

on(eventType, listener)

Subscribes to an element event. Returns an unsubscribe function — call it to remove the listener.

on(eventType: 'ready' | 'change' | 'focus' | 'blur' | 'error', listener: (event: CustomEvent) => void): () => void

const unsubscribe = cardNumberEl.on('change', (event) => {
  console.log(event.detail.isValid, event.detail.cardBrand);
});

// Later, when the listener is no longer needed:
unsubscribe();

See Events for the full payload reference for each event type.

---

React refs

In React, element methods are accessible via a ref. The ref type extends the base Element interface with three convenience state properties:

Property	Type	Description
complete	boolean	true when the input is valid and complete
empty	boolean	true when the input is empty
valid	boolean	true when the current value passes validation

The CardNumberElementRef also exposes cardBrand?, last4?, and bin?.

import { useRef } from 'react';
import { CardNumberElement, type CardNumberElementRef } from '@basis-theory/react-elements';

function PaymentForm() {
  const cardNumberRef = useRef<CardNumberElementRef>(null);

  const handleReset = () => {
    cardNumberRef.current?.clear();
  };

  const handleFocus = () => {
    cardNumberRef.current?.focus();
  };

  return (
    <>
      <CardNumberElement id="card-number" ref={cardNumberRef} />
      <button onClick={handleReset}>Clear</button>
      <button onClick={handleFocus}>Focus</button>
    </>
  );
}

---

Example: full element interaction

Web Elements

import BasisTheory from '@basis-theory/web-elements';

const bt = BasisTheory('<PUBLIC_API_KEY>');

const cardNumber = bt.createElement('cardNumber', {
  placeholder: '4111 1111 1111 1111',
});

// Subscribe before mounting so you don't miss the ready event
const unsubReady = cardNumber.on('ready', () => {
  console.log('element ready, mounted:', cardNumber.mounted);
  unsubReady();
});

const unsubChange = cardNumber.on('change', (event) => {
  const { isValid, isEmpty, cardBrand } = event.detail;
  document.getElementById('submit').disabled = !isValid;
  if (cardBrand) document.getElementById('brand').textContent = cardBrand;
});

await cardNumber.mount('#card-number-container');

// Update placeholder after mount
await cardNumber.update({ placeholder: 'Card number' });

// On form reset
document.getElementById('reset').addEventListener('click', () => {
  cardNumber.clear();
});

// On teardown
function teardown() {
  unsubChange(); // remove listener
  cardNumber.unmount();
}

React Elements

import { useRef, useState } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  useBasisTheory,
} from '@basis-theory/react-elements';

function CardForm() {
  const { bt } = useBasisTheory();
  const cardRef = useRef(null);
  const [isValid, setIsValid] = useState(false);
  const [cardBrand, setCardBrand] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    const token = await bt.tokens.create({
      type: 'card',
      data: { number: cardRef.current },
    });
    console.log(token.id);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement
        id="card-number"
        ref={cardRef}
        placeholder="4111 1111 1111 1111"
        onReady={() => console.log('ready')}
        onChange={(event) => {
          setIsValid(event.detail.isValid);
          setCardBrand(event.detail.cardBrand ?? null);
        }}
      />
      {cardBrand && <span>{cardBrand}</span>}
      <button type="button" onClick={() => cardRef.current?.clear()}>
        Clear
      </button>
      <button type="submit" disabled={!isValid}>
        Submit
      </button>
    </form>
  );
}

export default function App() {
  return (
    <BasisTheoryProvider apiKey="<PUBLIC_API_KEY>">
      <CardForm />
    </BasisTheoryProvider>
  );
}