Link Search Menu Expand Document

Collect Customer Data (PII) with React

Basis Theory is built to handle any payload of data you can serialize. Once you’ve completed this guide, you’ll know how to use our React package to of how to collect and secure your customer’s PII (Personally Identifiable Information) data in 3 simple steps with our Elements, keeping it safe and secure.

If you’d like to follow along with this guide from scratch, we suggest creating a new React sandbox using and getting started from there! Want to jump right into our sample app? Find it here!

Let’s code

To start, you’ll need a Public Application with the token:pii:create permission. Click here to create one.

Install our dedicated React package:

npm install --save @basis-theory/basis-theory-react

Initialize the Basis Theory SDK passing the API Key to the useBasisTheory hook and wrap your App contents with a BasisTheoryProvider:

import {
} from '@basis-theory/basis-theory-react';

function App() {
    const { bt } = useBasisTheory(ELEMENTS_API_KEY, {
        elements: true,

    return (
        <BasisTheoryProvider bt={bt}>
            <!-- rest of app code goes here -->
export default App;

Create a RegistrationForm component and add it somewhere in your App content.

Create two refs that will be used to store the underlying elements instances.

Declare two TextElement tags inside it, one for the “Full Name”, and the other for the “Social Security Number”; then call the tokenize method passing the current elements instance from the refs:

import { useRef } from 'react';
import { TextElement, useBasisTheory } from '@basis-theory/basis-theory-react';

export const RegistrationForm = () => {
  const { bt } = useBasisTheory();
  const fullNameRef = useRef(null);
  const ssnRef = useRef(null);

  const submit = async () => {
      try {
          const response = await bt.tokenize({
              fullName: fullNameRef.current,
              ssn: {
                  type: 'social_security_number',
                  data: ssnRef.current,
      } catch (error) {
  return (
        <TextElement id="fullName" ref={fullNameRef} />
        <TextElement id="ssn" ref={ssnRef} />

Success! 🎉 Your application is now collecting and storing PII in Basis Theory platform.

Next steps

You can further customize the TextElement props to best suit your needs.

The Tokens you’ve created from your frontend application can be used in a variety of ways from within your system, check out a few of those below:

  • Fetched later in your servers, using a Private Application Key (click here to create one) to call Get a Token API;
  • Used to call on of our Reactors to process that data. Some use cases are:
    • Integrating with third party KYC platforms, such as Alloy;
    • Pull credit reports for your customers without touching their data;
    • Send e-mails or instant messages to communication channels;
    • Pull background checks;
  • Make a third party API request with the raw data through our Proxy.

See it in action

The example below uses a few of the Element’s user experience features to ensure the best experience to your customers:

  • Pass a mask to the ssn field, restricting user input to digits only and formatting the output;
  • Use a transform option in the ssn field to strip out dash ‘-‘ characters from the tokenized data;
  • Disable the “Submit” <button> while the fullName field is empty or the ssn field is not complete, by listening to their onChange event;
  • Disable both inputs and the “Submit” button during the tokenization request inside the submit function;
  • Display the full stringified tokens response;
  • Log any tokenization errors to the console;

See it running and the code that drives it below. Want to experience the sandbox yourself? Check it out here.