Elements Components

CardNumberElement

The CardNumberElement component features a card number input, by wrapping the React Native TextInput component, which makes its interface similar to working directly with a regular TextInput.

import React, { useRef } from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';
import {
  BTRef,
  CardNumberElement,
} from '@basis-theory/basis-theory-react-native';

const App = () => {
  const ref = useRef<BTRef>(null);

  return (
    <SafeAreaView>
      <StatusBar />
      <ScrollView contentInsetAdjustmentBehavior="automatic">
        <View style={styles.viewContainer}>
          <CardNumberElement
            btRef={ref}
            placeholder="Card Number"
            style={styles.cardNumber}
          />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  cardNumber: {
    backgroundColor: '#eeeeee',
    borderColor: 'blue',
    borderWidth: 2,
    color: 'purple',
    height: 40,
    margin: 12,
    padding: 10,
  },
  viewContainer: {
    display: 'flex',
    flexDirection: 'column',
    marginTop: 32,
  },
});

export default App;

Properties

Property	Required	Type	Description
`btRef`	false	object/function	Callback ref function to store/receive the Element instance. Review the using refs section for more information
`style`	false	object	React Native styles used to customize the Element appearance
`editable`	false	boolean	Boolean used to set the editable attribute of the Element
`placeholder`	false	string	String used to customize the placeholder attribute of the Element

Methods

The methods available to CardNumberElement can be accessed through the refs. Review the using refs section for more information.

Masking

Element masks enable user input to be restricted and formatted to meet a pre-defined format. The CardNumberElement automatically sets a mask based on the card brand.

Card Brands

The first several digits of the card number are analyzed as the user is typing to determine the card brand. The brand is used to automatically set a mask to a brand-specific format.

Supported card brands are defined in the table below:

Brand	Identifier	Card Number Digits	CVC Digits
American Express	`americanExpress`	15	4
Diners Club	`dinersClub`	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
React JS
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' )

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

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}
/>

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.

CardExpirationDateElement

The CardExpirationDateElement component features a card number input, by wrapping the React Native TextInput component, which makes its interface similar to working directly with a regular TextInput.

import React, { useRef } from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';
import {
  BTRef,
  CardExpirationDateElement,
} from '@basis-theory/basis-theory-react-native';

const App = () => {
  const ref = useRef<BTRef>(null);

  return (
    <SafeAreaView>
      <StatusBar />
      <ScrollView contentInsetAdjustmentBehavior="automatic">
        <View style={styles.viewContainer}>
          <CardExpirationDateElement
            btRef={ref}
            placeholder="Card Expiration Date"
            style={styles.cardExpiration}
          />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  cardExpiration: {
    backgroundColor: '#eeeeee',
    borderColor: 'blue',
    borderWidth: 2,
    color: 'purple',
    height: 40,
    margin: 12,
    padding: 10,
  },
  viewContainer: {
    display: 'flex',
    flexDirection: 'column',
    marginTop: 32,
  },
});

export default App;

Properties

Property	Required	Type	Description
`btRef`	false	object/function	Callback ref function to store/receive the Element instance. Review the using refs section for more information
`style`	false	object	React Native styles used to customize the Element appearance
`editable`	false	boolean	Boolean used to set the editable attribute of the Element
`placeholder`	false	string	String used to customize the placeholder attribute of the Element

Methods

The methods available to CardExpirationDateElement can be accessed through the refs. Review the using refs section for more information.

Masking

Element masks enable user input to be restricted and formatted to meet a pre-defined format. The CardExpirationDateElement automatically sets a mask of MM/YY.

CardVerificationCodeElement

The CardVerificationCodeElement component features a card number input, by wrapping the React Native TextInput component, which makes its interface similar to working directly with a regular TextInput.

import React, { useRef } from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';
import {
  BTRef,
  CardVerificationCodeElement,
} from '@basis-theory/basis-theory-react-native';

const App = () => {
  const ref = useRef<BTRef>(null);

  return (
    <SafeAreaView>
      <StatusBar />
      <ScrollView contentInsetAdjustmentBehavior="automatic">
        <View style={styles.viewContainer}>
          <CardVerificationCodeElement
            btRef={ref}
            placeholder="CVC"
            style={styles.cvc}
          />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  cvc: {
    backgroundColor: '#eeeeee',
    borderColor: 'blue',
    borderWidth: 2,
    color: 'purple',
    height: 40,
    margin: 12,
    padding: 10,
  },
  viewContainer: {
    display: 'flex',
    flexDirection: 'column',
    marginTop: 32,
  },
});

export default App;

Properties

Property	Required	Type	Description
`btRef`	false	object/function	Callback ref function to store/receive the Element instance. Review the using refs section for more information
`style`	false	object	React Native styles used to customize the Element appearance
`editable`	false	boolean	Boolean used to set the editable attribute of the Element
`placeholder`	false	string	String used to customize the placeholder attribute of the Element

Methods

The methods available to CardVerificationCodeElement can be accessed through the refs. Review the using refs section for more information.

Masking

Element masks enable user input to be restricted and formatted to meet a pre-defined format. The CardVerificationCodeElement automatically sets a mask of 4 digits.

TextElement

The TextElement component features a text input that wraps the React Native TextInput component, which makes its interface similar to working directly with a regular TextInput.

import React, { useRef } from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';
import {
  BTRef,
  TextElement,
} from '@basis-theory/basis-theory-react-native';

const App = () => {
  const ref = useRef<BTRef>(null);

  return (
    <SafeAreaView>
      <StatusBar />
      <ScrollView contentInsetAdjustmentBehavior="automatic">
        <View style={styles.viewContainer}>
          <TextElement
            btRef={ref}
            placeholder="Phone Number"
            mask={["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/]}
            style={styles.phoneNumber}
          />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  phoneNumber: {
    backgroundColor: '#eeeeee',
    borderColor: 'blue',
    borderWidth: 2,
    color: 'purple',
    height: 40,
    margin: 12,
    padding: 10,
  },
  viewContainer: {
    display: 'flex',
    flexDirection: 'column',
    marginTop: 32,
  },
});

export default App;

Properties

Property	Required	Type	Description
`btRef`	false	object/function	Callback ref function to store/receive the Element instance. Review the using refs section for more information
`editable`	false	boolean	Boolean used to set the editable attribute of the Element
`mask`	false	array	Restricts and formats input entered into the TextElement. Masking
`placeholder`	false	string	String used to customize the placeholder attribute of the Element
`placeholderTextColor`	false	string	String used to customize the placeholderTextColor attribute of the Element
`style`	false	object	React Native styles used to customize the Element appearance

Methods

The methods available to TextElement can be accessed through the refs. Review the using refs section for more information.

Masking

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

The input must be at most 13 characters long.
Only digits are allowed in the 2nd to 4th, 6th to 8th, and 10th to 13th positions.
( will be filled in the 1st position.
) will be filled in the 5th position.
- will be filled in the 8th 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 onChange events and will fail validation before tokenization.

<TextElement
  btRef={ref}
  placeholder="Phone Number"
  mask={["(", /\d/, /\d/, /\d/, ")", /\d/, /\d/, /\d/, "-", /\d/, /\d/, /\d/, /\d/]}
/>

Elements Components

CardNumberElement​

Properties​

Methods​

Masking​

Card Brands​

Customizing Card Brands​

The CreditCardType​

niceType (or Brand)​

type (or Identifier)​

gaps​

lengths​

code​

Example​

CardExpirationDateElement​

Properties​

Methods​

Masking​

CardVerificationCodeElement​

Properties​

Methods​

Masking​

TextElement​

Properties​

Methods​

Masking​

CardNumberElement

Properties

Methods

Masking

Card Brands

Customizing Card Brands

The `CreditCardType`

`niceType` (or Brand)

`type` (or Identifier)

`gaps`

`lengths`

`code`

Example

CardExpirationDateElement

Properties

Methods

Masking

CardVerificationCodeElement

Properties

Methods

Masking

TextElement

Properties

Methods

Masking