JavaScript Elements SDK
JavaScript Elements SDK
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
- yarn
- CDN
npm install --save @basis-theory/basis-theory-js
yarn add @basis-theory/basis-theory-js
<!-- Including this tag will export a global/window "BasisTheory" variable -->
<script src="https://js.basistheory.com"></script>
>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.
- ES Module
- CDN
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
<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("<API_KEY>", { 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. |
BasisTheory.js
as a module, make sure the instance that loads elements runs on the browser-side code.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.