Skip to main content

JavaScript Elements SDK

JavaScript Elements SDK

basis-theory-js

The Basis Theory JavaScript SDK makes it easy to build secure web applications that collect or reveal sensitive data using Elements.

Get started with our guide, explore our examples, or continue reading the reference docs.

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 Javascript SDK 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

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

npm install --save @basis-theory/basis-theory-js
The Basis Theory JS SDK >1.77.0 is not compatible with Create React App v5.0.0 or above due to a known issue.

Initialization

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

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

// In this context BasisTheory is a class
const bt = await new BasisTheory().init("<API_KEY>", { elements: true });
// use Elements
ParameterRequiredTypeDescription
apiKeytruestringThe API Key used to identify an Application.
optionsfalseBasisTheoryInitOptionsOptions for initializing the BasisTheory instance.

Basis Theory Init Options

AttributeRequiredTypeDescription
elementsfalsebooleanBoolean 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.