Initialization

Installation

npm install @basis-theory-ai/react@beta --save

React Provider Setup

import { BasisTheoryProvider, useBasisTheory } from '@basis-theory-ai/react';
 
function App() {
  // Get JWT token from your backend
  const apiKey = 'YOUR_JWT_TOKEN'; // This should be a JWT, not a static key
  
  return (
    <BasisTheoryProvider 
      apiKey={apiKey}
      environment="production" // or "sandbox" for testing
    >
      <YourApp />
    </BasisTheoryProvider>
  );
}
 
function YourApp() {
  const { bt, isInitialized, isLoading, initError } = useBasisTheory();
  
  // Handle loading state
  if (isLoading) {
    return <div>Loading BasisTheory SDK...</div>;
  }
 
  // Handle initialization errors
  if (initError) {
    return <div>Error initializing SDK: {initError.message}</div>;
  }
 
  // Handle not yet initialized
  if (!isInitialized) {
    return <div>Initializing...</div>;
  }
 
  // SDK is ready to use
  return (
    <div>
      <h1>BasisTheory SDK Ready!</h1>
      <p>Session Key: {bt?.sessionKey}</p>
    </div>
  );
}

Hook Usage Example

import { useBasisTheory } from '@basis-theory/react-sdk';
 
function PaymentComponent() {
  const { 
    bt,           // BasisTheory SDK instance
    isInitialized, // Boolean: is SDK ready
    isLoading,     // Boolean: is SDK initializing  
    initError,     // Error object if initialization failed
    apiKey,        // Current API key/JWT
    environment,   // Current environment
    getSessionKey, // Helper: get session key
    isReady,       // Helper: check if ready for use
    getStatus      // Helper: get current status string
  } = useBasisTheory();
 
  if (!isReady()) {
    return <div>SDK Status: {getStatus()}</div>;
  }
 
  return (
    <div>
      <p>SDK is ready with session key: {getSessionKey()}</p>
    </div>
  );
}

Configuration Options

BasisTheoryProvider Props

useBasisTheory Hook Returns

Hook Usage Example

import { useBasisTheory } from '@basis-theory-ai/react';
 
function PaymentComponent() {
  const { 
    bt,           // BasisTheory SDK instance
    isInitialized, // Boolean: is SDK ready
    isLoading,     // Boolean: is SDK initializing  
    initError,     // Error object if initialization failed
    apiKey,        // Current API key/JWT
    environment,   // Current environment
    getSessionKey, // Helper: get session key
    isReady,       // Helper: check if ready for use
    getStatus      // Helper: get current status string
  } = useBasisTheory();
 
  if (!isReady()) {
    return <div>SDK Status: {getStatus()}</div>;
  }
 
  return (
    <div>
      <p>SDK is ready with session key: {getSessionKey()}</p>
    </div>
  );
}

Error Handling

The SDK handles several types of initialization errors:

Common Errors

• Invalid API key format: Empty or malformed JWT token
• Invalid environment: Environment not “production” or “sandbox”
• SDK not loaded: BasisTheory script not included in HTML
• Already initialized: SDK instance already exists (handled gracefully)

Error Handling Example

function ErrorHandlingExample() {
  const { initError, isLoading, isInitialized } = useBasisTheory();
 
  if (isLoading) return <div>Loading...</div>;
  
  if (initError) {
    // Handle specific error types
    if (initError.message.includes('API key')) {
      return <div>Please provide a valid JWT token</div>;
    }
    
    if (initError.message.includes('BasisTheory SDK not loaded')) {
      return <div>Please include the BasisTheory script tag</div>;
    }
    
    return <div>Initialization error: {initError.message}</div>;
  }
  
  if (!isInitialized) return <div>Initializing...</div>;
  
  return <div>SDK Ready!</div>;
}

Important Notes

1. JWT Token: Despite the prop name apiKey, you must provide a valid JWT token, not a static API key
2. Script Dependency: The BasisTheory SDK script must be loaded before the provider initializes
3. Single Instance: The provider prevents duplicate initialization and reuses existing instances
4. Automatic Cleanup: The provider handles cleanup when components unmount
5. Environment: Use “sandbox” for development and testing, “production” for live applications