Elements

What are Elements?

Elements are secure, PCI-compliant iframes that enable your application to collect, display, and interact with sensitive data without it ever touching your systems. This approach significantly reduces your compliance scope and security risk.

Key Benefits

• Reduced PCI Scope - Collect card data without the burden of full PCI compliance
• Enhanced Security - Sensitive data never touches your systems or frontend code
• Developer Friendly - Simple API with intuitive React components or vanilla JS implementation
• Customizable UI - Style Elements to match your application's design
• Secure Tokenization - Create tokens from collected data without exposing raw values

Available Implementations

Basis Theory offers two implementation options:

• Web Elements - Vanilla JavaScript SDK for any web application
• React Elements - React-specific SDK with hooks, components, and React-friendly patterns

Quick Start

1. Install the SDK

Web Elements

Web Elements

web-elements

Loading Stars

Loading Contributors

See it in GitHub

npm

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

yarn

yarn add @basis-theory/web-elements

CDN

<script src="https://js.basistheory.com/web-elements/latest/index.js"></script>

React Elements

React Elements

react-elements

Loading Stars

Loading Contributors

See it in GitHub

npm

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

yarn

yarn add @basis-theory/react-elements

2. Initialize the SDK

Web Elements

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

// Initialize with your API key
const bt = await basistheory("<YOUR_API_KEY>");

React Elements

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

function App() {
  // Initialize with your API key using the hook
  const { bt } = useBasisTheory("<YOUR_API_KEY>");
  
  return (
    <BasisTheoryProvider bt={bt}>
      {/* Your app content */}
    </BasisTheoryProvider>
  );
}

3. Create and Use Elements

Web Elements

// Create a card element
const cardElement = bt.createElement('card', {
  targetId: 'my-card'
});

// Mount it to a container in your DOM
cardElement.mount('#card-container');

// Tokenize the data when ready
document.getElementById('payment-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const { token } = await bt.tokenize({
    card: cardElement
  });
  
  console.log('Token created:', token.id);
});

React Elements

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

function PaymentForm() {
  const { bt } = useBasisTheory();
  const cardRef = useRef(null);
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    
    const { token } = await bt.tokenize({
      card: cardRef.current
    });
    
    console.log('Token created:', token.id);
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <CardElement id="my-card" ref={cardRef} />
      <button type="submit">Pay Now</button>
    </form>
  );
}

Before You Begin

Both Element SDKs require an API Key associated with a Public Application with appropriate permissions like token:create. This limits the risk of exposing API keys in your frontend code.

To create one:

1. Log in to the Basis Theory Portal
2. Create a new "Public" Application
3. Select only the permissions you need (typically token:create and possibly token:update)

Never use Management or Private API keys in frontend code.

API Naming Conventions

Both Element SDKs use JavaScript camelCase for method and property names, which are automatically converted to snake_case when communicating with the Basis Theory API. One notable exception is the Tokenize method which directly accepts snake_case for request bodies.

Learn More

• Detailed initialization guide
• Components reference
• Element methods
• Event handling
• Services (tokenization, sessions and proxy)
• Element lifecycle
• Troubleshooting guide