Skip to main content

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​

PropertyRequiredTypeDescription
btReffalseobject/functionCallback ref function to store/receive the Element instance. Review the using refs section for more information
stylefalseobjectReactNative styles used to customize the Element appearance
editablefalsebooleanBoolean used to set the editable attribute of the Element
placeholderfalsestringString 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:

BrandIdentifierCard Number DigitsCVC Digits
American ExpressamericanExpress154
Diners ClubdinersClub14, 16, 193
Discoverdiscover16, 193
Eloelo163
Hiperhiper163
HiperCardhipercard163
JCBjcb16-193
Maestromaestro12-193
Mastercardmastercard163
MIRmir16-193
UnionPayunionPay14-193
Visavisa16, 18, 193
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.

BrandNameSize
VisaCVV3
MastercardCVC3
American ExpressCID4
Diners ClubCVV3
DiscoverCID3
JCBCVV3
UnionPayCVN3
MaestroCVC3
MirCVP23
EloCVE3
HiperCVC3
HipercardCVC4

Example​

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]
});

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​

PropertyRequiredTypeDescription
btReffalseobject/functionCallback ref function to store/receive the Element instance. Review the using refs section for more information
stylefalseobjectReactNative styles used to customize the Element appearance
editablefalsebooleanBoolean used to set the editable attribute of the Element
placeholderfalsestringString 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​

PropertyRequiredTypeDescription
btReffalseobject/functionCallback ref function to store/receive the Element instance. Review the using refs section for more information
stylefalseobjectReactNative styles used to customize the Element appearance
editablefalsebooleanBoolean used to set the editable attribute of the Element
placeholderfalsestringString 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.