JavaScript Elements SDK

Basis Theory Elements are secure inputs that empower developers to easily collect or reveal sensitive data within web or mobile applications.

Think about it as an isolated sandbox within your frontend application that your end users are able to seamlessly interact with, and which securely communicates with the Basis Theory Vault. Sensitive data is not directly exposed to your application code, which keeps your frontend systems out of compliance scope.

Here's how we make this possible:

• Integrate our web and mobile SDKs into your frontend applications
• Build forms using our Element input components
• Interact with the Basis Theory API using Element references, not plaintext data
• Own your UI/UX by fully customizing how Elements are styled

Collect Sensitive Data

Data entered by your end users into Elements is tokenized and secured within Basis Theory's certified Vault.

Our SDKs provide several types of inputs to collect various types of data, such as the CardElement for collecting credit card data and TextElement for collecting arbitrary textual data.

Elements can be configured to support custom input masking, validation, and transformation rules to satisfy your use cases.

Reveal Sensitive Data

Tokens stored within the Basis Theory Vault can be securely revealed to end users without accessing the plaintext data directly within your application code.

Using one of our SDKs, sensitive data can be securely retrieved and applied to one or more Elements within your UI. See the section below on detokenization for more information.

Revealing sensitive data is only currently supported within the JavaScript and React SDKs. We are working to fully support this functionality within our native Android and iOS SDKs. Interested? Please email us at info@basistheory.comto join our early access program.

Before You Begin

Basis Theory Elements require the use of an API Key associated with a Public Application, which only allows the use of token:create and token:update permissions, removing any risk that your API keys are stolen and used to access data.

To create one, login into our Portal and create a new "Public" Application with the permissions you require.

Installation

To install BasisTheory.js you can choose either our ES module or CDN hosted bundle through a script tag.

npm

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

yarn

yarn add @basis-theory/basis-theory-js

CDN

<!-- Including this tag will export a global/window "BasisTheory" variable -->
<script src="https://js.basistheory.com"></script>

Initialization

Initialize BasisTheory with elements: true to dynamically loads Elements module.

ES Module

import { BasisTheory } from "@basis-theory/basis-theory-js";

// In this context BasisTheory is a class
const bt = await new BasisTheory().init("test_1234567890", { elements: true });
// use Elements

CDN

<script>
  // you can initialize it wherever it suits your workflow best
  // here we are waiting for the window to load, to make sure BasisTheory instance
  // has been injected in the window variable
  window.addEventListener('load', async () => {
    try {
      // global/window variable BasisTheory is an instance, but requires initialization
      await BasisTheory.init('test_1234567890', { elements: true });
      // use Elements
    } catch (e) {
      // handle errors that could happen while loading elements script
    }
  });
</script>

Parameter	Required	Type	Description
apiKey	true	string	The API Key used to identify an Application.
options	false	BasisTheoryInitOptions	Options for initializing the BasisTheory instance.

Basis Theory Init Options

Attribute	Required	Type	Description
elements	false	boolean	Boolean used to indicate whether the BasisTheory instance will have Elements capabilities.

Elements are meant to be used in browser environments only. If you installed BasisTheory.js as a module, make sure the instance that loads elements runs on the browser-side code.

If you try to to use any Elements feature before calling BasisTheory.init, or before its Promise has been fulfilled, you will get an error.

Usage with TypeScript

Starting at 1.14.0, BasisTheory.js bundles all TypeScript definitions for Elements features. You don't have to take any extra steps in order to use it.