Initialization

This page covers installing the SDK, initializing it in your project, and the available configuration options.

Installation

Web Elements

npm

npm install --save @basis-theory/web-elements

yarn

yarn add @basis-theory/web-elements

CDN

1

After the script loads, window.BasisTheory is available as the factory function.

React Elements

npm

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

yarn

yarn add @basis-theory/react-elements

When using React Elements, you do not need to install @basis-theory/web-elements separately — it is included as a dependency.

---

Initialization

Web Elements

ES module:

import BasisTheory from '@basis-theory/web-elements';

const bt = BasisTheory('<PUBLIC_API_KEY>');

const cardNumber = bt.createElement('cardNumber', {
  placeholder: '4111 1111 1111 1111',
});

await cardNumber.mount('#card-number-container');

BasisTheory() is synchronous — it returns the SDK instance immediately with no await needed.

CDN / script tag:

1

<script>
  document.addEventListener('DOMContentLoaded', async () => {
    const bt = window.BasisTheory('<PUBLIC_API_KEY>');

    const cardNumber = bt.createElement('cardNumber', {
      placeholder: '4111 1111 1111 1111',
    });

    await cardNumber.mount('#card-number-container');
  });
</script>

React Elements

Wrap your application (or the subtree that uses elements) in BasisTheoryProvider. Pass your public API key via the apiKey prop.

import { BasisTheoryProvider, useBasisTheory } from '@basis-theory/react-elements';

function App() {
  return (
    <BasisTheoryProvider apiKey="<PUBLIC_API_KEY>">
      <PaymentForm />
    </BasisTheoryProvider>
  );
}

function PaymentForm() {
  const { bt } = useBasisTheory(); // reads SDK instance from context

  // bt is null if initialization failed; check error from context if needed
  if (!bt) return null;

  return (/* your form */);
}

useBasisTheory() takes no arguments — it reads the SDK instance from the nearest BasisTheoryProvider.

---

SDK options

These options are passed as the second argument to BasisTheory(), or as the options prop on BasisTheoryProvider.

Option	Type	Default	Description
debug	boolean	false	Enable verbose debug logging to the browser console.
allowHttpClient	boolean	false	Allow bt.client.* to send element data directly to a third-party destination (dual writing). Frozen at initialization. Destinations must also be allowlisted by Basis Theory.
sessionAuthorizationUrl	string	—	Endpoint on your backend that authorizes the session used by cardDisplay. Required by that element and ignored by the others. Must be https://, except on localhost and 127.0.0.1; relative paths resolve against your page's origin.
themeMode	'light' | 'dark' | 'auto'	'auto'	Controls which theme tokens are applied. 'auto' follows the OS prefers-color-scheme.
theme	ThemeTokens	—	Light-mode design tokens. See Theming.
darkTheme	ThemeTokens	—	Dark-mode design tokens. If omitted and dark mode is active, falls back to theme.
direction	'ltr' | 'rtl'	'ltr'	Writing direction applied to every element. See Right-to-Left.
language	string	—	BCP 47 tag applied to every element, for assistive technology. See Right-to-Left.

---

Framework-specific setup

Next.js

Elements require browser APIs and DOM access, so they must only be initialized on the client side. Mark any component that uses elements with "use client":

// components/PaymentForm.tsx
"use client";

import { useRef } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  ExpiryElement,
  CVVElement,
  useBasisTheory,
} from '@basis-theory/react-elements';

function PaymentFormInner() {
  const { bt } = useBasisTheory();
  const cardNumberRef = useRef(null);
  const expiryRef = useRef(null);
  const cvvRef = useRef(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const token = await bt!.tokens.create({
      type: 'card',
      data: {
        number: cardNumberRef.current,
        expiration_month: expiryRef.current,
        expiration_year: expiryRef.current,
        cvc: cvvRef.current,
      },
    });
    console.log(token.id);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement id="card-number" ref={cardNumberRef} />
      <ExpiryElement id="expiry" ref={expiryRef} />
      <CVVElement id="cvv" ref={cvvRef} />
      <button type="submit">Pay</button>
    </form>
  );
}

export default function PaymentForm() {
  return (
    <BasisTheoryProvider apiKey={process.env.NEXT_PUBLIC_BASIS_THEORY_KEY!}>
      <PaymentFormInner />
    </BasisTheoryProvider>
  );
}

Nuxt.js

Register Elements as a client-only plugin to prevent server-side rendering errors:

// plugins/basistheory.client.js
import BasisTheory from '@basis-theory/web-elements';

export default defineNuxtPlugin(() => {
  const bt = BasisTheory(process.env.BASIS_PUBLIC_API_KEY);
  return {
    provide: { bt },
  };
});

Then access the SDK in your components via useNuxtApp().$bt.

Don't see your framework? Reach out to support@basistheory.com and we'll help you integrate.

---

Best practices

1. Single instance — Create one SDK instance and share it throughout your application rather than calling BasisTheory() in multiple places.
2. Public keys only — Never use Private API keys in frontend code. Only pk_ keys belong in the browser.
3. CSP headers — If you use Content Security Policy, allow frame-src and script-src for *.basistheory.com. See the security guide.
4. SRI for CDN usage — When loading the SDK via a CDN <script> tag, add an integrity attribute to verify the file has not been tampered with. See Subresource Integrity.