Elements Components

CardElement

The CardElement component features a full credit card form, wrapping the Card Element type functionality and taking care of the React lifecycle. The Card Element contains the following inputs:

• cardNumber
• expirationDate
  • Must not be expired or greater than 19 years in the future
• cvc

Live Card Element

import {
  BasisTheoryProvider,
  CardElement,
  useBasisTheory,
} from "@basis-theory/basis-theory-react";

const App = () => {
  // creates a new instance of BasisTheory class
  const { bt } = useBasisTheory("<API_KEY>", { elements: true });

  return (
    <BasisTheoryProvider bt={bt}>
      <MyComponent />
    </BasisTheoryProvider>
  );
};

const MyComponent = () => {
  return <CardElement id="myCard" />; // Element will grab instance from the Context
};

Properties

Property	Required	Type	Updatable	Description
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s).
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
copyIconStyles	false	object	false	Object used to customize the copy icon size, color and successColor
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
enableCopy	false	boolean	false	Renders a button to allow users to copy the value of the element to the browser's clipboard without your application ever interacting with the data.
id	true	string	false	String identifier used to retrieve the Element instance for tokenization.
inputMode	false	string	true	String used to set the inputmode attribute of the input(s)
onBlur	false	function	true	Event Listener. See On Blur
onChange	false	function	true	Event Listener. See On Change
onFocus	false	function	true	Event Listener. See On Focus
onKeyDown	false	function	true	Event Listener. See On Keydown
onReady	false	function	true	Event Listener. See On Ready
placeholder	false	string	true	Object used to customize the placeholder attribute of the inputs. Card element takes a CardElementPlaceholder object
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
style	false	object	true	Object used to customize the element appearance
validateOnChange	false	boolean	false	Enable validation onChange
value	false	string	true	Sets a static value for the element input.

enableCopy is available for Chromium-based browsers only; we're actively working on multi-browser support. Have feedback or questions? Feel free to join us in our Slack community.

Card Element Placeholder

interface CardElementPlaceholder {
  cardNumber?: string;
  cardExpirationDate?: string;
  cardSecurityCode?: string;
}

TextElement

The TextElement component features a regular text input for collecting any input data, by wrapping the Text Element type functionality and taking care of the React lifecycle.

Live Text Element

import {
  BasisTheoryProvider,
  TextElement,
  useBasisTheory,
} from "@basis-theory/basis-theory-react";

const App = () => {
  // creates a new instance of BasisTheory class
  const { bt } = useBasisTheory("<API_KEY>", { elements: true });

  return (
    <BasisTheoryProvider bt={bt}>
      <MyComponent />
    </BasisTheoryProvider>
  );
};

const MyComponent = () => {
  return <TextElement id="myInput" placeholder="John Doe" />; // Element will grab instance from the Context
};

Properties

Property	Required	Type	Updatable	Description
aria-label	false	string	true	String used to customize the aria-label attribute of the input
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s).
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
inputMode	false	string	true	String used to set the inputmode attribute of the input(s)
mask	false	array	false	Array used to restrict and fill user input using regex and static strings
maxLength	false	number	false	Defines the maximum string length that the user can enter into the TextElement. Learn more
onBlur	false	function	true	Event listener. See On Blur
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onKeyDown	false	function	true	Event listener. See On Keydown
onReady	false	function	true	Event listener. See On Ready
password	false	boolean	true	Boolean used to set the text element input type as password
placeholder	false	string	true	String used to customize the placeholder attribute of the input
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
style	false	object	true	Object used to customize the element appearance
transform	false	RegExp	true	RegExp object or array used to modify user input before tokenization
validateOnChange	false	boolean	false	Enable validation onChange
validation	false	RegExp	true	[RegExp object] used to validate user input. Runs validation on blur by default
value	false	string	true	Sets a static value for the element input.
valueRef	false	TextElement reference	false	Sets the element's value to the value of the provided element.

When using valueRef to keep an element in sync with another element, or to set the text of an element, it is strongly recommended that you make the element that is being acted upon readOnly. This is possible by setting readOnly to true.

CardNumberElement

The CardNumberElement component features a card number input, by wrapping the Card Number Element type functionality and taking care of the React lifecycle.

Live Card Number Element

import {
  BasisTheoryProvider,
  CardNumberElement,
  useBasisTheory,
} from "@basis-theory/basis-theory-react";

const App = () => {
  // creates a new instance of BasisTheory class
  const { bt } = useBasisTheory("<API_KEY>", { elements: true });

  return (
    <BasisTheoryProvider bt={bt}>
      <MyComponent />
    </BasisTheoryProvider>
  );
};

const MyComponent = () => {
  return <CardNumberElement id="cardNumber" />; // Element will grab instance from the Context
};

Properties

Property	Required	Type	Updatable	Description
aria-label	false	string	true	String used to customize the aria-label attribute of the input
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s).
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
copyIconStyles	false	object	false	Object used to customize the copy icon size, color and successColor
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
enableCopy	false	boolean	false	Renders a button to allow users to copy the value of the element to the browser's clipboard without your application ever interacting with the data.
iconPosition	false	string	true	String used to determine the position of the card brand icon. Expected values are: left (default), right or none.
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
inputMode	false	string	true	String used to set the inputmode attribute of the input(s)
onBlur	false	function	true	Event listener. See On Blur
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onKeyDown	false	function	true	Event listener. See On Keydown
onReady	false	function	true	Event listener. See On Ready
placeholder	false	string	true	String used to customize the placeholder attribute of the input
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
style	false	object	true	Object used to customize the element appearance
validateOnChange	false	boolean	false	Enable validation onChange
value	false	string	true	Sets a static value for the element input.
valueRef	false	CardNumberElement reference	false	Sets the element's value to the value of the provided element.

enableCopy is available for Chromium-based browsers only; we're actively working on multi-browser support. Have feedback or questions? Feel free to join us in our Slack community.

When using valueRef to keep an element in sync with another element, or to set the text of an element, it is strongly recommended that you make the element that is being acted upon readOnly. This is possible by setting readOnly to true.

CardExpirationDateElement

The CardExpirationDateElement component features a card expiration date input, by wrapping the Card Expiration Date Element type functionality and taking care of the React lifecycle. The date must not be expired or greater than 19 years in the future

Live Card Expiration Date Element

import {
  BasisTheoryProvider,
  CardExpirationDateElement,
  useBasisTheory,
} from "@basis-theory/basis-theory-react";

const App = () => {
  // creates a new instance of BasisTheory class
  const { bt } = useBasisTheory("<API_KEY>", { elements: true });

  return (
    <BasisTheoryProvider bt={bt}>
      <MyComponent />
    </BasisTheoryProvider>
  );
};

const MyComponent = () => {
  return <CardExpirationDateElement id="cardExpirationDate" />; // Element will grab instance from the Context
};

Properties

Property	Required	Type	Updatable	Description
aria-label	false	string	true	String used to customize the aria-label attribute of the input
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s).
copyIconStyles	false	object	false	Object used to customize the copy icon size, color and successColor
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
enableCopy	false	boolean	false	Renders a button to allow users to copy the value of the element to the browser's clipboard without your application ever interacting with the data.
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
inputMode	false	string	true	String used to set the inputmode attribute of the input(s)
onBlur	false	function	true	Event listener. See On Blur
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onKeyDown	false	function	true	Event listener. See On Keydown
onReady	false	function	true	Event listener. See On Ready
placeholder	false	string	true	String used to customize the placeholder attribute of the input
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
style	false	object	true	Object used to customize the element appearance
validateOnChange	false	boolean	false	Enable validation onChange
value	false	string	true	Sets a static value for the element input.
valueRef	false	CardExpirationDateElement reference	false	Sets the element's value to the value of the provided element.

enableCopy is available for Chromium-based browsers only; we're actively working on multi-browser support. Have feedback or questions? Feel free to join us in our Slack community.

When using valueRef to keep an element in sync with another element, or to set the text of an element, it is strongly recommended that you make the element that is being acted upon readOnly. This is possible by setting readOnly to true.

CardVerificationCodeElement

The CardVerificationCodeElement component features a card security code input, by wrapping the Card Verification Code Element type functionality and taking care of the React lifecycle.

Live Card Verification Code Element

import {
  BasisTheoryProvider,
  CardVerificationCodeElement,
  useBasisTheory,
} from "@basis-theory/basis-theory-react";

const App = () => {
  // creates a new instance of BasisTheory class
  const { bt } = useBasisTheory("<API_KEY>", { elements: true });

  return (
    <BasisTheoryProvider bt={bt}>
      <MyComponent />
    </BasisTheoryProvider>
  );
};

const MyComponent = () => {
  return <CardVerificationCodeElement id="cardVerificationCode" />; // Element will grab instance from the Context
};

Properties

Property	Required	Type	Updatable	Description
aria-label	false	string	true	String used to customize the aria-label attribute of the input
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s).
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
cardBrand	false	string	true	String used to determine proper input format and default placeholder/aria-label
copyIconStyles	false	object	false	Object used to customize the copy icon size, color and successColor
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
enableCopy	false	boolean	false	Renders a button to allow users to copy the value of the element to the browser's clipboard without your application ever interacting with the data.
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
inputMode	false	string	true	String used to set the inputmode attribute of the input(s)
onBlur	false	function	true	Event listener. See On Blur
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onKeyDown	false	function	true	Event listener. See On Keydown
onReady	false	function	true	Event listener. See On Ready
placeholder	false	string	true	String used to customize the placeholder attribute of the input
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
style	false	object	true	Object used to customize the element appearance
validateOnChange	false	boolean	false	Enable validation onChange
value	false	string	true	Sets a static value for the element input.
valueRef	false	CardVerificationCodeElement reference	false	Sets the element's value to the value of the provided element.

enableCopy is available for Chromium-based browsers only; we're actively working on multi-browser support. Have feedback or questions? Feel free to join us in our Slack community.

When using valueRef to keep an element in sync with another element, or to set the text of an element, it is strongly recommended that you make the element that is being acted upon readOnly. This is possible by setting readOnly to true.

Error Handling

Any errors occurring during the element mounting phase are thrown intentionally during the render cycle. Consider using React's error boundaries to handle these errors gracefully. When using React class components, you can also implement the methods getDerivedStateFromError and componentDidCatch to handle component errors appropriately.