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
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)
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
inputMode	false	string	true	String used to set the inputmode 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.
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.

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
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)
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
inputMode	false	string	true	String used to set the inputmode 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.
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.
validation	false	RegExp	true	[RegExp object] used to validate user input (on match) before tokenization

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
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)
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
inputMode	false	string	true	String used to set the inputmode 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.
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
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)
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
inputMode	false	string	true	String used to set the inputmode 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.
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
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)
readOnly	false	boolean	true	Boolean used to set the readonly attribute of the input(s)
inputMode	false	string	true	String used to set the inputmode 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.
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.