Skip to main content

Initialization

This document covers setting up Elements in your project, from installation to initialization, with examples for common scenarios.

Installation Options​

npm install --save @basis-theory/web-elements
When using React Elements, you don't need to install @basis-theory/web-elements separately as it's included as a dependency.
React Elements SDK >1.12.1 is not compatible with Create React App v5.0.0 or above due to a known issue.

Initialization​

import { basistheory } from "@basis-theory/web-elements";

// Async initialization
const bt = await basistheory("<PUBLIC_API_KEY>");

// Now bt is ready to use
const cardElement = bt.createElement('card', {
  targetId: 'my-card'
});

Initialization Options​

PropertyDefault ValueDescription
debugfalseWhen enabled, the library will append a debug object to every response payload to help you trace and diagnose rendering or integration issues step by step.
disableTelemetryfalseOpts out of sending anonymous usage metrics, error reports, and performance data back to Basis Theory.
useSameOriginApitrueRoutes all API calls through the same origin (https://js.basistheory.com/api), leveraging HTTP/2 connection reuse and eliminating CORS preflight overhead—resulting in lower latency and fewer round-trips.

Best Practices​

  1. Single Instance: Create one Elements instance and share it throughout your application
  2. Loading States: Show appropriate loading indicators while Elements initialize
  3. Error Handling: Always wrap initialization in try/catch blocks
  4. Lazy Loading: For applications where Elements are only needed in specific sections, consider lazy-loading the Elements library
  5. API Key Security: Only use Public API keys in frontend code
If you're experiencing CSP (Content Security Policy) errors, make sure your policy allows connections to *.basistheory.com domains for both script sources and frame-src directives.

Framework-Specific Setup​

Next.js​

When using Basis Theory Elements with Next.js, you need to ensure the Elements are only initialized on the client side. This is because Elements require browser-specific APIs and DOM access.

Here's how to properly set up Elements in a Next.js application:

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

import { useRef } from "react";
import { CardElement, useBasisTheory } from "@basis-theory/react-elements";

const CreditCardForm = () => {
  const cardRef = useRef<ICardElement | null>(null);
  const { bt } = useBasisTheory(process.env.NEXT_PUBLIC_BASIS_THEORY_KEY);

  const handleSubmit = async (event: React.FormEvent) => {
    event.preventDefault();
    try {
      const token = await bt.tokens.create({
        type: "card",
        data: cardRef.current,
      });
      // Handle the token
    } catch (err) {
      console.error("Tokenization error", err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement id="card" bt={bt} ref={cardRef} />
      <button type="submit">Submit</button>
    </form>
  );
};

export default CreditCardForm;

For a complete Next.js implementation example, check out our Next.js Example Repository.

Nuxt.js​

For Nuxt.js applications, you'll need to set up Elements as a client-side plugin. Here's how to configure it:

// plugins/basistheory.js
import Vue from "vue";
import { basistheory } from "@basis-theory/web-elements";

export default async ({ $config }, inject) => {
  try {
    const bt = await basistheory(process.env.BASIS_PUBLIC_API_KEY);
    inject("bt", bt);
  } catch (e) {
    console.error("Basis Theory init error", e);
  }
};
// nuxt.config.js
export default {
  plugins: [{ src: "~/plugins/basistheory.js", mode: "client" }],
  build: {
    transpile: ["@basis-theory/web-elements"],
  },
  publicRuntimeConfig: {
    basisPublicApiKey: process.env.BASIS_PUBLIC_API_KEY,
  },
};

For a complete Nuxt.js implementation example, check out our Nuxt.js Example Repository.

Don't see your framework here? We're happy to help you integrate Basis Theory Elements with your specific tech stack. Reach out to us support@basistheory.com

Troubleshooting Initialization​

If you encounter any issues during initialization, such as Elements not loading or displaying correctly, please refer to our troubleshooting guide.

For specific environment configurations like Content Security Policy settings, see the CSP documentation.

For framework specific considerations visit this section.