Skip to main content

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("test_1234567890", { elements: true });

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

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

Properties

PropertyRequiredTypeUpdatableDescription
idtruestringfalseString identifier used to retrieve the Element instance for tokenization.
btfalseReact Elements SDKfalseInstance used by the Element. Will use instance from BasisTheoryProvider if configured.
stylefalseobjecttrueObject used to customize the element appearance
disabledfalsebooleantrueBoolean used to set the disabled attribute of the input(s)
readOnlyfalsebooleantrueBoolean used to set the readonly attribute of the input(s)
inputModefalsestringtrueString used to set the inputmode attribute of the input(s)
autoCompletefalsestringtrueString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
onReadyfalsefunctiontrueEvent Listener. See On Ready
onChangefalsefunctiontrueEvent Listener. See On Change
onFocusfalsefunctiontrueEvent Listener. See On Focus
onBlurfalsefunctiontrueEvent Listener. See On Blur
onKeyDownfalsefunctiontrueEvent Listener. See On Keydown
reffalseobject/functionfalseRef object/Callback ref function to store/receive the Element instance.
validateOnChangefalsebooleanfalseEnable validation onChange
enableCopyfalsebooleanfalseRenders 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.
valuefalsestringtrueSets 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("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

PropertyRequiredTypeUpdatableDescription
idtruestringfalseString identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
btfalseReact Elements SDKfalseInstance used by the Element. Will use instance from BasisTheoryProvider if configured.
stylefalseobjecttrueObject used to customize the element appearance
disabledfalsebooleantrueBoolean used to set the disabled attribute of the input(s)
readOnlyfalsebooleantrueBoolean used to set the readonly attribute of the input(s)
inputModefalsestringtrueString used to set the inputmode attribute of the input(s)
autoCompletefalsestringtrueString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
maskfalsearrayfalseArray used to restrict and fill user input using regex and static strings
transformfalseRegExptrueRegExp object or array used to modify user input before tokenization
placeholderfalsestringtrueString used to customize the placeholder attribute of the input
aria-labelfalsestringtrueString used to customize the aria-label attribute of the input
passwordfalsebooleantrueBoolean used to set the text element input type as password
onReadyfalsefunctiontrueEvent listener. See On Ready
onChangefalsefunctiontrueEvent listener. See On Change
onFocusfalsefunctiontrueEvent listener. See On Focus
onBlurfalsefunctiontrueEvent listener. See On Blur
onKeyDownfalsefunctiontrueEvent listener. See On Keydown
reffalseobject/functionfalseRef object/Callback ref function to store/receive the Element instance.
valuefalsestringtrueSets a static value for the element input.
validationfalseRegExptrue[RegExp object] used to validate user input (on match) before tokenization

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

PropertyRequiredTypeUpdatableDescription
idtruestringfalseString identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
btfalseReact Elements SDKfalseInstance used by the Element. Will use instance from BasisTheoryProvider if configured.
stylefalseobjecttrueObject used to customize the element appearance
disabledfalsebooleantrueBoolean used to set the disabled attribute of the input(s)
readOnlyfalsebooleantrueBoolean used to set the readonly attribute of the input(s)
inputModefalsestringtrueString used to set the inputmode attribute of the input(s)
autoCompletefalsestringtrueString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
iconPositionfalsestringtrueString used to determine the position of the card brand icon. Expected values are: left (default), right or none.
placeholderfalsestringtrueString used to customize the placeholder attribute of the input
aria-labelfalsestringtrueString used to customize the aria-label attribute of the input
onReadyfalsefunctiontrueEvent listener. See On Ready
onChangefalsefunctiontrueEvent listener. See On Change
onFocusfalsefunctiontrueEvent listener. See On Focus
onBlurfalsefunctiontrueEvent listener. See On Blur
onKeyDownfalsefunctiontrueEvent listener. See On Keydown
reffalseobject/functionfalseRef object/Callback ref function to store/receive the Element instance.
validateOnChangefalsebooleanfalseEnable validation onChange
enableCopyfalsebooleanfalseRenders 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.
valuefalsestringtrueSets 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.

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("test_1234567890", { elements: true });

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

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

Properties

PropertyRequiredTypeUpdatableDescription
idtruestringfalseString identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
btfalseReact Elements SDKfalseInstance used by the Element. Will use instance from BasisTheoryProvider if configured.
stylefalseobjecttrueObject used to customize the element appearance
disabledfalsebooleantrueBoolean used to set the disabled attribute of the input(s)
readOnlyfalsebooleantrueBoolean used to set the readonly attribute of the input(s)
inputModefalsestringtrueString used to set the inputmode attribute of the input(s)
autoCompletefalsestringtrueString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
placeholderfalsestringtrueString used to customize the placeholder attribute of the input
aria-labelfalsestringtrueString used to customize the aria-label attribute of the input
onReadyfalsefunctiontrueEvent listener. See On Ready
onChangefalsefunctiontrueEvent listener. See On Change
onFocusfalsefunctiontrueEvent listener. See On Focus
onBlurfalsefunctiontrueEvent listener. See On Blur
onKeyDownfalsefunctiontrueEvent listener. See On Keydown
reffalseobject/functionfalseRef object/Callback ref function to store/receive the Element instance.
validateOnChangefalsebooleanfalseEnable validation onChange
enableCopyfalsebooleanfalseRenders 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.
valuefalsestringtrueSets 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.

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

PropertyRequiredTypeUpdatableDescription
idtruestringfalseString identifier used to retrieve the Element instance for tokenization. This is passed through to the targetId option.
btfalseReact Elements SDKfalseInstance used by the Element. Will use instance from BasisTheoryProvider if configured.
stylefalseobjecttrueObject used to customize the element appearance
disabledfalsebooleantrueBoolean used to set the disabled attribute of the input(s)
readOnlyfalsebooleantrueBoolean used to set the readonly attribute of the input(s)
inputModefalsestringtrueString used to set the inputmode attribute of the input(s)
autoCompletefalsestringtrueString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
cardBrandfalsestringtrueString used to determine proper input format and default placeholder/aria-label
placeholderfalsestringtrueString used to customize the placeholder attribute of the input
aria-labelfalsestringtrueString used to customize the aria-label attribute of the input
onReadyfalsefunctiontrueEvent listener. See On Ready
onChangefalsefunctiontrueEvent listener. See On Change
onFocusfalsefunctiontrueEvent listener. See On Focus
onBlurfalsefunctiontrueEvent listener. See On Blur
onKeyDownfalsefunctiontrueEvent listener. See On Keydown
reffalseobject/functionfalseRef object/Callback ref function to store/receive the Element instance.
validateOnChangefalsebooleanfalseEnable validation onChange
enableCopyfalsebooleanfalseRenders 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.
valuefalsestringtrueSets 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.

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.