Elements Properties

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

Attribute	Required	Type	Updatable	Eligible Elements	Description
aria-label	false	string	true	text cardNumber cardExpirationDate cardVerificationCode	String used to customize the aria-label attribute of the input
autoComplete	false	string	true	All	String used to set the autocomplete attribute of the input(s). Expected values are: off (default), or on.
cardBrand	false	string	true	cardVerificationCode	Brand identifier used to determine proper input format and default placeholder/aria-label
cardTypes	false	array	false	cardNumber	List of CreditCardTypes for custom BIN validation, intended to extend the pre-defined card brand validation rules or override them altogether.
disabled	false	boolean	true	All	Boolean used to set the disabled attribute of the input(s)
enableCopy	false	boolean	true	cardNumber cardExpirationDate cardElement cardVerificationCode	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	cardNumber	String used to determine the position of the card element icon. Expected values are: left (default), right or none.
inputMode	false	string	true	All	String used to set the inputmode attribute of the input(s)
mask	false	array	false	text	Array used to restrict and fill user input using regex and static strings
password	false	boolean	true	text	Boolean used to set the text element input type as password
placeholder	false	string	true	text cardNumber cardExpirationDate cardVerificationCode	String used to customize the placeholder attribute of the input
readOnly	false	boolean	true	All	Boolean used to set the readonly attribute of the input(s)
skipLuhnValidation	false	boolean	false	cardElement cardNumber	Disables Luhn Validation for Card Element and Card Number Element
style	false	object	true	All	Object used to customize the element appearance
targetId	true	string	false	text cardNumber cardExpirationDate cardVerificationCode	String used to identify your element
transform	false	RegExp	true	text	RegExp object or array used to modify user input before tokenization
validateOnChange	false	boolean	false	cardNumber cardExpirationDate cardElement cardVerificationCode	Switches from default validation onBlur to onChange.
value	false	string	true	All	Sets a static value for the element input.

When using some end-to-end testing frameworks and using the default validation onBlur, you may need to force the blur events to trigger the validation due to framework-specific limitations.

1. Switching the validation strategy from onBlur to onChange will change the sequence and increase the number of events. When running validations onChange, elements emit events whenever an error occurs or if the input's value changes. Default validation onBlur triggers an event every time one of the properties in the changeEvent changes.


2. 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.


3. skipLuhnValidation deactivates the most basic card validation mechanism. Recommended for testing purposes only.


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


5. 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.

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",
    },
  },
});

Attribute	Required	Type	Description
fonts	false	array	Array of Google Fonts URLs
base	false	object	Base variant style - all other variant styles inherit from this one
complete	false	object	Variant style applied when the element input is complete
empty	false	object	Variant style applied when the element input has no value
invalid	false	object	Variant 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:

• backgroundColor
• color
• fontFamily
• fontSize
• fontSmooth (we replace this with the user-agent alternate names automatically)
• fontStyle
• fontVariant
• fontWeight
• lineHeight
• letterSpacing
• textAlign
• padding
• textDecoration
• textShadow
• textTransform

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

Supported card brands are defined in the table below:

Brand	Identifier	Card Number Digits	CVC Digits
American Express	american-express	15	4
Diners Club	diners-club	14, 16, 19	3
Discover	discover	16, 19	3
Elo	elo	16	3
Hiper	hiper	16	3
HiperCard	hipercard	16	3
JCB	jcb	16-19	3
Maestro	maestro	12-19	3
Mastercard	mastercard	16	3
MIR	mir	16-19	3
UnionPay	unionpay	14-19	3
Visa	visa	16, 18, 19	3

Some card brands have issued card numbers with multiple lengths. The Card Number Digits column documents all acceptable card number lengths for the brand (in number of digits, excluding formatting characters).

Customizing Card Brands

You can extend default card brands to include additional BIN numbers or create custom card brands by modifying the cardType property of the CardNumberElement.

The CreditCardType

We implement credit-card-type for our JS SDKs to manage card brands, so we borrow some of their concepts and apply them to all of our SDKs

type CreditCardType = {
    code: { 
        size: number; 
        name: SecurityCodeLabel | string; // CVV, CVC, CID, etc.
    };
    gaps: number[]; 
    lengths: number[];
    niceType: CardBrandNiceType | string; // or card brand
    patterns: (number | [number, number])[];
    type: CardBrandId | string; // or card identifier
};

niceType (or Brand)

A pretty printed representation of the card brand.

• Visa
• Mastercard
• American Express
• Diners Club
• Discover
• JCB
• UnionPay
• Maestro
• Mir
• Elo
• Hiper
• Hipercard

type (or Identifier)

A code-friendly presentation of the card brand.

• visa
• mastercard
• american-express
• diners-club
• discover
• jcb
• unionpay
• maestro
• mir
• elo
• hiper
• hipercard

gaps

The expected indices of gaps in a string representation of the card number. For example, in a Visa card, 4111 1111 1111 1111, there are expected spaces in the 4th, 8th, and 12th positions.

lengths

The expected lengths of the card number as an array of strings (excluding spaces and / characters).

code

The information regarding the security code for the determined card.

Card brands provide different nomenclature for their security codes as well as varying lengths.

Brand	Name	Size
Visa	CVV	3
Mastercard	CVC	3
American Express	CID	4
Diners Club	CVV	3
Discover	CID	3
JCB	CVV	3
UnionPay	CVN	3
Maestro	CVC	3
Mir	CVP2	3
Elo	CVE	3
Hiper	CVC	3
Hipercard	CVC	4

Example

JavaScript

import { VISA, DEFAULT_CARD_TYPES, type CreditCardType } from "@basis-theory/basis-theory-js/types/elements"

const CUSTOM_VISA = {
  ...VISA,
    // Add new BIN pattern '8456' and maintain pre-existing ones
  patterns: [...VISA.patterns, 8456],
};

// removes pre-existing Visa CreditCardType
const CustomCardTypesList = DEFAULT_CARD_TYPES.filter(({ type }: CreditCardType) => type != 'visa' )

const cardNumberElement = BasisTheory.createElement('cardNumber', {
  targetId: 'cardNumberElement',
  // Adds filtered CreditCardType's list and custom visa CreditCardType
  cardTypes: [...CustomCardTypesList, CUSTOM_VISA]
});

React JS

import { VISA, DEFAULT_CARD_TYPES, type CreditCardType } from "@basis-theory/basis-theory-js/types/elements"

const CUSTOM_VISA = {
  ...VISA,
    // Add new BIN pattern '8456' and maintain pre-existing ones
  patterns: [...VISA.patterns, 8456],
};

// removes pre-existing Visa CreditCardType
const CustomCardTypesList = DEFAULT_CARD_TYPES.filter(({ type }: CreditCardType) => type != 'visa' )
...
<CardNumberElement
  btRef={ref}  
  cardTypes={[...CustomCardTypesList, CUSTOM_VISA]}
  placeholder="Card Number"
  style={styles.cardNumber}
/>

React Native

import { VISA, DEFAULT_CARD_TYPES, type CreditCardType } from "@basis-theory/basis-theory-js/types/elements"

const CUSTOM_VISA = {
  ...VISA,
    // Add new BIN pattern '8456' and maintain pre-existing ones
  patterns: [...VISA.patterns, 8456],
};

// removes pre-existing Visa CreditCardType
const CustomCardTypesList = DEFAULT_CARD_TYPES.filter(({ type }: CreditCardType) => type != 'visa' )
...
<CardNumberElement
  btRef={ref}  
  cardTypes={[...CustomCardTypesList, CUSTOM_VISA]}
  placeholder="Card Number"
  style={styles.cardNumber}
/>

When adding custom card brands the default list is replaced, and validation will only run against those brands defined in the cardTypes list.

For more granular control, we expose card brands individually and a list with all the default card brands.