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

Before You Begin

Both Element SDKs require an API Key associated with a Public Application with the token:create permission. Public keys are safe to use in frontend code because they can only create tokens, not read sensitive data.

To create one:

1. Log in to the Basis Theory Portal
2. Create a new "Public" Application
3. Grant the token:create permission (and token:update if needed)

Never use Management or Private API keys in frontend code. They can read raw token data and must stay server-side.

Quick Start

1. Install the SDK

Web Elements

npm

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

yarn

yarn add @basis-theory/web-elements@beta

CDN

1

React Elements

npm

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

yarn

yarn add @basis-theory/react-elements@beta

2. Initialize the SDK

Web Elements

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

// Synchronous — returns immediately, no await needed
const bt = BasisTheory('<PUBLIC_API_KEY>');

React Elements

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

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

3. Create and Use Elements

Web Elements

const cardNumberEl = bt.createElement('cardNumber');
const expiryEl = bt.createElement('expiry');
const cvvEl = bt.createElement('cvv');

await Promise.all([
  cardNumberEl.mount('#card-number'),
  expiryEl.mount('#expiry'),
  cvvEl.mount('#cvv'),
]);

document.getElementById('payment-form').addEventListener('submit', async (e) => {
  e.preventDefault();

  const token = await bt.tokens.create({
    type: 'card',
    data: {
      number: cardNumberEl,
      expiration_month: expiryEl,
      expiration_year: expiryEl,
      cvc: cvvEl,
    },
  });

  console.log('Token created:', token.id);
});

React Elements

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

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

  const handleSubmit = async (e) => {
    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 created:', token.id);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement ref={cardNumberRef} />
      <ExpiryElement ref={expiryRef} />
      <CVVElement ref={cvvRef} />
      <button type="submit">Pay Now</button>
    </form>
  );
}

Browser Support

Web Elements supports the latest versions of modern browsers:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Mobile and WebView Environments

Web Elements works in mobile browsers and WebView environments, but requires:

• Latest browser engines with full support for modern JavaScript APIs
• Secure context (https:// origin recommended)
• Proper WebView configuration for cross-origin iframe communication

For detailed guidance on mobile environments and compatibility considerations, see the troubleshooting guide.

Learn More

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