Skip to main content

Elements Options

You can customize the behavior of your Elements using the following options:

AttributeRequiredTypeUpdatableEligible ElementsDescription
stylefalseobjecttrueAllObject used to customize the element appearance
disabledfalsebooleantrueAllBoolean used to set the disabled attribute of the input(s)
autoCompletefalsestringtrueAllString used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
targetIdtruestringfalsetext
cardNumber
cardExpirationDate
cardVerificationCode
String used to identify your element
placeholderfalsestringtruetext
cardNumber
cardExpirationDate
cardVerificationCode
String used to customize the placeholder attribute of the input
aria-labelfalsestringtruetext
cardNumber
cardExpirationDate
cardVerificationCode
String used to customize the aria-label attribute of the input
maskfalsearrayfalsetextArray used to restrict and fill user input using regex and static strings
transformfalseRegExptruetextRegExp object or array used to modify user input before tokenization
passwordfalsebooleantruetextBoolean used to set the text element input type as password
iconPositionfalsestringtruecardNumberString used to determine the position of the card element icon. Expected values are: left (default), right or none.
cardBrandfalsestringtruecardVerificationCodeString used to determine proper input format and default placeholder/aria-label
valuefalsestringtrueAllSets a static value for the element input.

The mask option cannot be used when the password option is set as true.

The autoComplete option is turned off by default, contrary to the default browser behavior which is on.

Using the value attribute instead of user input may have compliance implications.

Style

Elements are styled through the ElementStyle object, which maps state variants and miscellaneous.

var cardElement = BasisTheory.createElement("card", {
style: {
fonts: [
"https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,200;0,300;0,400;0,600;0,700;0,900;1,200;1,300;1,400;1,600;1,700;1,900&display=swap",
],
base: {
color: "#fff",
fontWeight: 500,
fontFamily: '"Inter"',
fontSize: "16px",
fontSmooth: "antialiased",
"::placeholder": {
color: "#6b7294",
},
":disabled": {
backgroundColor: "#f0f0f4",
},
},
invalid: {
color: "#ffc7ee",
},
complete: {
color: "#1ad1db",
},
},
});
AttributeRequiredTypeDescription
fontsfalsearrayArray of Google Fonts URLs
basefalseobjectBase variant style - all other variant styles inherit from this one
completefalseobjectVariant style applied when the element input has valid value
emptyfalseobjectVariant style applied when the element input has no value
invalidfalseobjectVariant style applied when the element input has invalid value

You can customize the following pseudo-classes and pseudo-elements inside each variant using a nested object:

  • :hover
  • :focus
  • :disabled
  • ::placeholder
  • ::selection

Here is a complete list of the supported CSS properties:

Variants are resolved per element input. In other words, variant styles will be applied on each element input individually based on their own value.

For security reasons, we currently support only the 1000+ Google Fonts families. If you need a custom font in your Basis Theory Elements, don't hesitate to reach out.

Mask

Text elements can restrict and fill user input by using the mask attribute. It consists of an array of RegExp objects and strings, used to restrict and fill input, respectively. The position of each item in the mask array corresponds to the restriction or fill used for that input's position. The length of the array determines how long an input is allowed to be. For example, the mask for a US based phone number shown on the right will have the following rules:

  • The input must be at most 13 characters long
  • Only digits are allowed in the 2-4, 6-8, 10-13 positions
  • '(' will be filled in the 1 position
  • ')' will be filled in the 5 position
  • '-' will be filled in the 8 position

The mask will be displayed as the user is typing, and will be used as the value for tokenization performed with that text element. If the value does not satisfy the mask in its entirety, the field is considered incomplete. This is reflected in the on change events and will fail validation before tokenization.

var phoneNumberElement = BasisTheory.createElement("text", {
targetId: "myPhoneNumberElement",
mask: ["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/]
});

Once set, we do not currently allow updating the mask. If you need to update the mask programmatically, don't hesitate to reach out.

For security and performance reasons, we attempt to detect that the regex provided is valid and not susceptible to catastrophic backtracking. If it fails this validation, we will reject the mount promise.

Transform

Text elements allow you to modify user input before tokenization through the transform attribute. It can be set as a RegExp object, an array with a RegExp object, or an array with a RegExp object at the first index and a string at the second. It works by making use of the String replace function. The RegExp object and string defined will be used as the first and second argument for the replace function, respectively. If no string is defined, an empty string will be used as the second argument. For instance, the mask for a US based phone number shown on the right will modify user input to look like this: (123)456-7890. The transform attribute, in this case, will modify the user input to remove (, ), and - from the input. The resulting value is 1234567890 which will be what gets tokenized.

var phoneNumberElement = BasisTheory.createElement("text", {
targetId: "myPhoneNumberElement",
mask: ["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/],
transform: /[()-]/,
});

We strip all RegExp object flags defined in the transform and set gu as the flags.

For security and performance reasons, we attempt to detect that the regex provided is valid and not susceptible to catastrophic backtracking. If it fails this validation, we will reject the mount or update promise.

Card Brands

The following list maps supported Card Brands to their values:

BrandValue
American Expressamerican-express
Diners Clubdiners-club
Discoverdiscover
Eloelo
Hiperhiper
HiperCardhipercard
JCBjcb
Maestromaestro
Mastercardmastercard
MIRmir
UnionPayunionpay
Visavisa
Unknownunknown

If you don't see the card brand you're looking for, please contact us!