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.

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("test_1234567890", { 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
id	true	string	false	String identifier used to retrieve the Element instance for tokenization.
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
style	false	object	true	Object used to customize the element appearance
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
onReady	false	function	true	Event Listener. See On Ready
onChange	false	function	true	Event Listener. See On Change
onFocus	false	function	true	Event Listener. See On Focus
onBlur	false	function	true	Event Listener. See On Blur
onKeyDown	false	function	true	Event Listener. See On Keydown
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
validateOnChange	false	boolean	false	Enable validation onChange
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.

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.

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("test_1234567890", { 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
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
style	false	object	true	Object used to customize the element appearance
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
mask	false	array	false	Array used to restrict and fill user input using regex and static strings
transform	false	RegExp	true	RegExp object or array used to modify user input before tokenization
placeholder	false	string	true	String used to customize the placeholder attribute of the input
aria-label	false	string	true	String used to customize the aria-label attribute of the input
password	false	boolean	true	Boolean used to set the text element input type as password
onReady	false	function	true	Event listener. See On Ready
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onBlur	false	function	true	Event listener. See On Blur
onKeyDown	false	function	true	Event listener. See On Keydown
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.

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("test_1234567890", { 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
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
style	false	object	true	Object used to customize the element appearance
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
iconPosition	false	string	true	String used to determine the position of the card brand icon. Expected values are: left (default), right or none.
placeholder	false	string	true	String used to customize the placeholder attribute of the input
aria-label	false	string	true	String used to customize the aria-label attribute of the input
onReady	false	function	true	Event listener. See On Ready
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onBlur	false	function	true	Event listener. See On Blur
onKeyDown	false	function	true	Event listener. See On Keydown
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
validateOnChange	false	boolean	false	Enable validation onChange
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.

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.

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.

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("test_1234567890", { 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
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
style	false	object	true	Object used to customize the element appearance
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
placeholder	false	string	true	String used to customize the placeholder attribute of the input
aria-label	false	string	true	String used to customize the aria-label attribute of the input
onReady	false	function	true	Event listener. See On Ready
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onBlur	false	function	true	Event listener. See On Blur
onKeyDown	false	function	true	Event listener. See On Keydown
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
validateOnChange	false	boolean	false	Enable validation onChange
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.

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.

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("test_1234567890", { 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
id	true	string	false	String identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
bt	false	React Elements SDK	false	Instance used by the Element. Will use instance from BasisTheoryProvider if configured.
style	false	object	true	Object used to customize the element appearance
disabled	false	boolean	true	Boolean used to set the disabled attribute of the input(s)
autoComplete	false	string	true	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
cardBrand	false	string	true	String used to determine proper input format and default placeholder/aria-label
placeholder	false	string	true	String used to customize the placeholder attribute of the input
aria-label	false	string	true	String used to customize the aria-label attribute of the input
onReady	false	function	true	Event listener. See On Ready
onChange	false	function	true	Event listener. See On Change
onFocus	false	function	true	Event listener. See On Focus
onBlur	false	function	true	Event listener. See On Blur
onKeyDown	false	function	true	Event listener. See On Keydown
ref	false	object/function	false	Ref object/Callback ref function to store/receive the Element instance.
validateOnChange	false	boolean	false	Enable validation onChange
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.

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.

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.