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/react-native-elements';

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
autoComplete	false	string	Hints to the OS what the field holds so it can offer saved card data. Use cc-number. See Autofill. Learn more
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
enterKeyHint	false	string	Label for the keyboard's action key, e.g. next or done. Pair with onSubmitEditing to advance between fields. Learn more
inputAccessoryViewID (iOS)	false	string	ID of an InputAccessoryView rendered above the keyboard, for a custom toolbar. Learn more
keyboardType	false	string	Determines which keyboard to open, e.g.numeric. Learn more
placeholder	false	string	String used to customize the placeholder attribute of the Element
returnKeyType	false	string	Label for the keyboard's return key, e.g. next or done. Ignored when enterKeyHint is also set. Learn more
style	false	object	React Native styles used to customize the Element appearance
textContentType (iOS)	false	string	Semantic meaning of the content, for the keyboard and system. Use creditCardNumber. See Autofill. Learn more
skipLuhnValidation	false	boolean	Boolean used to skip the Luhn validation of the card number. Default is false.
binLookup	false	boolean	Boolean used to enable BIN lookup for card details. When enabled, binDetails will be included in change events. Default is false.
coBadgedSupport	false	CoBadgedSupport[]	Array of supported co-badge networks. When enabled, selectedNetwork will be included in change events. See Co-Badge Support.
onChange	false	function	Callback function that is called when the element's value changes. Receives a ChangeEvent object.
onSubmitEditing	false	function	Callback function that is called when the keyboard's action key is pressed. Receives a ChangeEvent object rather than React Native's native event, so the entered value is never exposed.

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

Vault and Elements may return different card brands. While we aim for consistency, Vault might include brands that Elements doesn't support, and its brand identifiers may differ slightly in format. Refer to the Tokens Card Brands Table for differences.

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.

ChangeEvent

The CardNumberElement emits change events when the user types or modifies the input. The event object contains information about the element's state and, when enabled, BIN lookup and co-badge data.

ChangeEvent Properties

Property	Type	Description
complete	boolean	Whether the input is valid and satisfies the mask requirements
empty	boolean	Whether the input is empty
valid	boolean	Whether the input is valid according to validation rules
maskSatisfied	boolean	Whether the input satisfies the mask length requirements
cardBrand	string?	The detected card brand (e.g., "visa", "mastercard")
cardLast4	string?	The last 4 digits of the card number when complete
cardBin	string?	The first 6 or 8 digits of the card number when complete
binDetails	BinDetails?	Card BIN details when binLookup is enabled. See BinDetails
selectedNetwork	CardBrand?	The selected payment network for co-badged cards. Only present when co-badge support is enabled

BinDetails

When binLookup is enabled on a CardNumberElement, the element will automatically perform a BIN lookup and include the results in the binDetails property of the ChangeEvent.

BinDetails Properties

Property	Type	Description
brand	string?	The card brand (e.g., "visa", "mastercard")
funding	string?	The funding type (e.g., "credit", "debit", "prepaid")
issuer	object?	The issuing bank information with name and country properties
segment	string?	The card segment type
binRange	BinRange[]?	List of BIN ranges for the primary card brand
additional	CardInfo[]?	List of additional card information for co-badged cards

Usage Example

import { CardNumberElement, type ChangeEvent } from '@basis-theory/basis-theory-react-native';

const handleCardNumberChange = (event: ChangeEvent) => {
  console.log('Complete:', event.complete);
  console.log('Card Brand:', event.cardBrand);
  
  // Access BIN details when binLookup is enabled
  if (event.binDetails) {
    console.log('Funding type:', event.binDetails.funding);
    console.log('Issuer:', event.binDetails.issuer?.name);
    
    // Check for co-badged cards
    if (event.binDetails.additional && event.binDetails.additional.length > 0) {
      console.log('Co-badged card detected');
    }
  }
  
  // Access co-badge data when coBadgedSupport is enabled
  if (event.selectedNetwork) {
    console.log('Selected network:', event.selectedNetwork);
  }
};

<CardNumberElement
  btRef={cardNumberRef}
  binLookup={true}
  coBadgedSupport={['cartes-bancaires']}
  onChange={handleCardNumberChange}
  placeholder="Card Number"
/>

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/react-native-elements';

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
autoComplete	false	string	Hints to the OS what the field holds so it can offer saved card data. Use cc-exp. See Autofill. Learn more
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
enterKeyHint	false	string	Label for the keyboard's action key, e.g. next or done. Pair with onSubmitEditing to advance between fields. Learn more
inputAccessoryViewID (iOS)	false	string	ID of an InputAccessoryView rendered above the keyboard, for a custom toolbar. Learn more
keyboardType	false	string	Determines which keyboard to open, e.g.numeric. Learn more
placeholder	false	string	String used to customize the placeholder attribute of the Element
returnKeyType	false	string	Label for the keyboard's return key, e.g. next or done. Ignored when enterKeyHint is also set. Learn more
style	false	object	React Native styles used to customize the Element appearance
textContentType (iOS)	false	string	Semantic meaning of the content, for the keyboard and system. Use creditCardExpiration (iOS 17+). See Autofill. Learn more
onChange	false	function	Callback function that is called when the element's value changes. Receives a ChangeEvent object.
onSubmitEditing	false	function	Callback function that is called when the keyboard's action key is pressed. Receives a ChangeEvent object rather than React Native's native event, so the entered value is never exposed.

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/react-native-elements';

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
cvcLength	false	number	Length of the security code. A cvcLength is included in the CardNumberElement ElementEvent once the CardNumberElement has been filled out. It should be passed to this field for stricter validation of the CardVerificationCodeElement. Default length is 3
autoComplete	false	string	Hints to the OS what the field holds so it can offer saved card data. Use cc-csc. See Autofill. Learn more
editable	false	boolean	Boolean used to set the editable attribute of the Element
enterKeyHint	false	string	Label for the keyboard's action key, e.g. next or done. Pair with onSubmitEditing to advance between fields. Learn more
inputAccessoryViewID (iOS)	false	string	ID of an InputAccessoryView rendered above the keyboard, for a custom toolbar. Learn more
keyboardType	false	string	Determines which keyboard to open, e.g.numeric. Learn more
placeholder	false	string	String used to customize the placeholder attribute of the Element
returnKeyType	false	string	Label for the keyboard's return key, e.g. next or done. Ignored when enterKeyHint is also set. Learn more
style	false	object	React Native styles used to customize the Element appearance
textContentType (iOS)	false	string	Semantic meaning of the content, for the keyboard and system. Use creditCardSecurityCode (iOS 17+). See Autofill. Learn more
onChange	false	function	Callback function that is called when the element's value changes. Receives a ChangeEvent object.
onSubmitEditing	false	function	Callback function that is called when the keyboard's action key is pressed. Receives a ChangeEvent object rather than React Native's native event, so the entered value is never exposed.

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/react-native-elements';

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
autoComplete	false	string	Hints to the OS what the field holds so it can offer a saved value. See Autofill. Learn more
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
enterKeyHint	false	string	Label for the keyboard's action key, e.g. next or done. Pair with onSubmitEditing to advance between fields. Learn more
inputAccessoryViewID (iOS)	false	string	ID of an InputAccessoryView rendered above the keyboard, for a custom toolbar. Learn more
keyboardType	false	string	Determines which keyboard to open, e.g.numeric. Learn more
mask	false	array	Restricts and formats input entered into the TextElement. Masking
maxLength	false	number	Defines the maximum string length that the user can enter into the TextElement. Learn more
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
returnKeyType	false	string	Label for the keyboard's return key, e.g. next or done. Ignored when enterKeyHint is also set. Learn more
secureTextEntry	false	boolean	If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Learn more
style	false	object	React Native styles used to customize the Element appearance
textContentType (iOS)	false	string	Give the keyboard and the system information about the expected semantic meaning for the content that users enter. See Autofill. Learn more
onChange	false	function	Callback function that is called when the element's value changes. Receives a ChangeEvent object.
onSubmitEditing	false	function	Callback function that is called when the keyboard's action key is pressed. Receives a ChangeEvent object rather than React Native's native event, so the entered value is never exposed.

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

Autofill

Card Elements can opt in to the operating system's saved card data, so users don't retype the card number, expiration and security code on every add-card flow.

Set autoComplete on every Element in the form, and textContentType alongside it on iOS:

<CardNumberElement
  autoComplete="cc-number"
  textContentType="creditCardNumber"
  btRef={cardNumberRef}
  placeholder="Card Number"
/>
<CardExpirationDateElement
  autoComplete="cc-exp"
  textContentType="creditCardExpiration"
  btRef={cardExpirationDateRef}
  placeholder="MM/YY"
/>
<CardVerificationCodeElement
  autoComplete="cc-csc"
  textContentType="creditCardSecurityCode"
  btRef={cvcRef}
  placeholder="CVC"
/>

These props declare what a field holds. They never fill it themselves. The OS decides whether to offer a suggestion, and shows nothing if the user has no saved card.

Accepting a suggestion behaves exactly like typing: the Element applies its mask, emits an onChange event with the resulting empty, complete, valid and errors state, and tokenizes to the same value. The card data goes straight from the OS into the Element and is never exposed to your application, so this does not widen your PCI scope.

What to expect from each prop

Every prop below is a hint passed through to the underlying TextInput. The operating system decides what to do with it, so a correctly configured Element can still show nothing. Basis Theory applies no defaults, so behavior is unchanged until you opt in.

Prop	What you should see	When nothing happens
autoComplete	The OS offers the user's saved card above the keyboard. Accepting it fills the Element and fires onChange.	The user has no saved card, or the form doesn't declare a full card across the three Elements (cc-number, cc-exp, cc-csc).
textContentType (iOS)	The iOS name for the same hint. When both are set, this one takes precedence.	On Android, where it is ignored entirely. On iOS 16 and below for creditCardExpiration and creditCardSecurityCode, which need iOS 17+.
enterKeyHint	The keyboard's action key is relabelled to next, done, go, and so on.	There is no action key to relabel. See the note on keyboardType below.
returnKeyType	The same relabelling as enterKeyHint.	enterKeyHint is also set, which takes precedence. Prefer enterKeyHint; this is the older name for the same behavior.
inputAccessoryViewID (iOS)	Your InputAccessoryView renders directly above the keyboard while the Element is focused.	On Android, or when no InputAccessoryView is mounted with a matching nativeID. The prop fails silently in both cases.
onSubmitEditing	Fires when the action key is pressed, receiving a ChangeEvent.	The keyboard has no action key to press, so the callback is unreachable.

keyboardType="number-pad" renders a keypad with no return key at all, which leaves enterKeyHint, returnKeyType and onSubmitEditing unreachable. Use keyboardType="numeric" if you rely on them, or attach your own toolbar through inputAccessoryViewID.

On compact keyboards such as numeric, iOS draws next as a > chevron instead of the word "Next". The prop is still applied; only the rendering differs.

Keyboard navigation

Pair enterKeyHint with onSubmitEditing to label the keyboard's action key and move the user field to field, instead of making them dismiss the keyboard between inputs.

<CardNumberElement
  btRef={cardNumberRef}
  enterKeyHint="next"
  onSubmitEditing={() => cardExpirationDateRef.current?.focus()}
  placeholder="Card Number"
/>
<CardExpirationDateElement
  btRef={cardExpirationDateRef}
  enterKeyHint="next"
  onSubmitEditing={() => cvcRef.current?.focus()}
  placeholder="MM/YY"
/>
<CardVerificationCodeElement
  btRef={cvcRef}
  enterKeyHint="done"
  onSubmitEditing={() => cvcRef.current?.blur()}
  placeholder="CVC"
/>

Pressing the action key on the first two Elements moves focus forward. On the last it dismisses the keyboard. onSubmitEditing receives a ChangeEvent, the same sanitized shape as onChange. It does not receive React Native's native event, whose payload would carry the value the user entered.

See What to expect from each prop for the keyboard types that leave these props with no action key to attach to.