React Native Elements SDK
React Native SDK
Basis Theory React Native is an open source package designed to allow you to quickly integrate Element features in your mobile application. Every Element is a thin wrapper around the React Native TextInput component, which makes its interface similar to working directly with a regular TextInput.
Utilizing these Elements is as simple as declaring them as a typical React Native Components and passing the required props.
Before You Begin
This SDK requires the use of an API Key associated with a Public Application, which only allows token:create
or token:update
permissions to mitigate the risk that these API keys may be publicly exposed within your frontend applications.
To create one, login into our Portal and create a new "Public" Application with the permissions you require.
Considerations
Basis Theory React Native uses conventional camel case for most methods and converts these properties to snake case when sending requests to the API. One notable exception to this is the Tokenize method which uses snake case for the request body.
Installation
- npm
- yarn
npm install --save @basis-theory/basis-theory-react-native
yarn add @basis-theory/basis-theory-react-native
Using an Element
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;
Using Refs
Refs are a way to access React component instances. You can pass in a ref
into the btRef
prop into any Basis Theory Element to store or receive the Element instance, to tokenize their value or call one of its methods. For security reasons,
we don't return the underlying TextInput ref
, but instead our own instance of ref
. The ref
that's returned
is an instance of BTRef
that has the following methods under the current
property:
Methods | Signature | Description |
---|---|---|
clear | () => void | Clears the value from the underlying TextInput |
focus | () => void | Focuses the underlying TextInput |
blur | () => void | Blurs the underlying TextInput |
setValue | (inputBTRef: InputBTRef) => void | Sets the value of the Element. The function takes in an InputBTRef which is returned from a Basis Theory service call |
month | () => void | Data-parsing method that resolves to the month value of the input date, where "January" = 1. |
year | () => void | Data-parsing method that resolves to the four-digit year value of the input date. |
import React, { useRef } from "react";
import { Button, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BTRef } from "@basis-theory/basis-theory-react-native";
const MyForm = () => {
const cardNumberRef = useRef<BTRef>(null);
const cardExpirationDateRef = useRef<BTRef>(null);
const cardVerificationCodeRef = useRef<BTRef>(null);
const clear = async () => {
cardNumberRef.current.clear();
cardExpirationDateRef.current.clear();
cardVerificationCodeRef.current.clear();
};
return (
<>
<CardNumberElement btRef={cardNumberRef} placeholder="Card Number" />
<CardExpirationDateElement btRef={cardExpirationDateRef} placeholder="Card Expiration Date" />
<CardVerificationCodeElement btRef={cardVerificationCodeRef} placeholder="CVC" />
<div>
<Button title="Clear" onPress={clear} />
</div>
</>
);
};
InputBTRef and InputBTDateRef
An InputBTRef
is an object that contains a reference to a sensitive value returned from a Basis Theory service call.
To set the value of an element, pass in an InputBTRef
to the setValue
method of an Element ref as shown below:
import React, { useRef } from "react";
import { CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement, BasisTheoryElements, BTRef } from "@basis-theory/basis-theory-react-native";
const MyForm = () => {
const cardNumberRef = useRef<BTRef>(null);
const cardExpirationDateRef = useRef<BTRef>(null);
const cardVerificationCodeRef = useRef<BTRef>(null);
const { bt } = useBasisTheory("<PUBLIC API KEY>");
const getCardData = async () => {
const proxyResponse = await bt?.proxy({
headers: {
"BT-API-KEY": "<SESSION_API_KEY>",
"BT-PROXY-KEY": "<YOUR PROXY KEY>",
},
method: "post",
});
cardNumberRef.current?.setValue(proxyResponse.json.cardNumber);
cardExpirationDateRef.current?.setValue(proxyResponse.json.expDate);
cardVerificationCodeRef.current?.setValue(proxyResponse.json.cvc);
};
return (
<>
<CardNumberElement btRef={cardNumberRef} placeholder="Card Number" />
<CardExpirationDateElement btRef={cardExpirationDateRef} placeholder="Card Expiration Date" />
<CardVerificationCodeElement btRef={cardVerificationCodeRef} placeholder="CVC" />
<div>
<button type="button" onClick={getCardData}>
"Get Card Data"
</button>
</div>
</>
);
};