This guide will walk you through the process of integrating the Capsule Modal into your web application. The Capsule Modal provides an easy-to-use, pre-built interface for user authentication and wallet management.

​
Prerequisites

To use Capsule, you need an API key. This key authenticates your requests to Capsule services and is essential for integration.

Don’t have an API key yet? Request access to the Developer Portal to create API keys, manage billing, teams, and more.

​
Dependency Installation

First, install the Capsule React SDK using your preferred package manager:

​
Using the Capsule SDK

Follow these steps to quickly integrate the Capsule Modal into your React application:

1

Create Capsule Client Instance

First, create a Capsule client instance. This instance will be used to interact with the Capsule SDK:

import Capsule, { Environment } from "@usecapsule/react-sdk";
const capsule = new Capsule(Environment.BETA, process.env.REACT_APP_CAPSULE_API_KEY);

// Verify the instance is created successfully
console.log("Capsule instance created:", capsule);

This step initializes the Capsule SDK with your API key and the chosen environment. If successful, you should see the Capsule instance logged in your console.

Capsule offers two hosted environments: Environment.BETA (alias Environment.DEVELOPMENT) for testing, and Environment.PROD (alias Environment.PRODUCTION) for live use. Select the environment that matches your current development phase.

2

Set Up Polyfills

Depending on your target environment, you may need to set up polyfills for certain features that Capsule relies on. Common polyfills include:

  • crypto
  • buffer
  • stream
  • process

The exact method for including these polyfills will depend on your build tool and framework. Here’s a general example using webpack:

// webpack.config.js
module.exports = {
  // ...other config
  resolve: {
    fallback: {
      crypto: require.resolve('crypto-browserify'),
      buffer: require.resolve('buffer/'),
      stream: require.resolve('stream-browserify'),
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer']
    })
  ]
};

Make sure to install the necessary packages (e.g., crypto-browserify, buffer, etc.) before using them in your config.

The specific polyfills and setup may vary based on your project’s needs and the framework you’re using. Consult your framework’s documentation for best practices on polyfilling or consult our troubleshooting guide for more information.

3

Integrate Capsule Modal

Now, integrate the Capsule Modal into your React component:

import React, { useState } from "react";
import { CapsuleModal } from "@usecapsule/react-sdk";
import "@usecapsule/react-sdk/styles.css";

function App() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <div>
      <button onClick={() => setIsOpen(true)}>Sign in with Capsule</button>
      <CapsuleModal
        capsule={capsule}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </div>
  );
}
export default App;

This creates a button that, when clicked, opens the Capsule Modal for user authentication. The Capsule Modal handles all aspects of user authentication and wallet management.

Make sure to import the Capsule CSS file (@usecapsule/react-sdk/styles.css) to apply the default styles to the modal.

4

Note for SSR Frameworks

If you’re using Next.js or another server-side rendering framework, you’ll need to use dynamic imports for the CapsuleModal component to avoid SSR-related issues. An example of dynamic import in Next.js:

import dynamic from 'next/dynamic';

const CapsuleModal = dynamic(
  () => import('@usecapsule/react-sdk').then((mod) => mod.CapsuleModal),
  { ssr: false }
);

This ensures that the CapsuleModal is only loaded on the client-side. You may need to adjust this approach based on your specific SSR framework.

Consult your framework’s documentation or community resources for best practices on integrating client-side components in SSR applications.

​
Customization

You can customize the appearance and behavior of the Capsule Modal to match your application’s branding. This includes both the modal itself and how Capsule interacts with your users outside of the modal.

​
Customizing Capsule Initialization

When initializing the Capsule instance, you can pass constructor options to customize various aspects of Capsule’s behavior:

const constructorOpts = {
  emailTheme: 'light',
  emailPrimaryColor: '#007bff',
  // ... other constructor options
};

const capsule = new Capsule(
  Environment.BETA,
  process.env.REACT_APP_CAPSULE_API_KEY,
  constructorOpts
);

​
Customizing the Capsule Modal

When rendering the CapsuleModal component, you can pass props to customize its appearance and behavior:

<CapsuleModal
  capsule={capsule}
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  appName="Your App Name"
  logo="https://yourapp.com/logo.png"
  theme={{
    backgroundColor: '#ffffff',
    foregroundColor: '#000000',
  }}
  oAuthMethods={['GOOGLE', 'TWITTER', 'DISCORD']}
/>

For a full list of available ConstructorOpts and CapsuleModalProps, refer to the customization guide:

Detailed Customization Guide

For more information on customizing the Capsule Modal and SDK, including advanced theming options, branding configurations, and external link management, check out our detailed customization guide.

​
Examples

For practical implementation of the Capsule SDK in React applications, explore our example repository:

Capsule React Integration Examples

Explore our repository containing React Native implementations, along with shared UI components demonstrating Capsule integration.

​
Next Steps

After integrating Capsule, you can explore other features and integrations to enhance your Capsule experience. Here are some resources to help you get started:

​
Ecosystems

Learn how to use Capsule with popular Web3 clients and wallet connectors. We’ll cover integration with key libraries for EVM, Solana, and Cosmos ecosystems.

EVM Integration

Learn how to use Capsule with EVM-compatible libraries like ethers.js, viem, and wagmi.

Solana Integration

Discover how to integrate Capsule with solana-web3.js.

Cosmos Integration

Explore Capsule integration with Cosmos ecosystem using CosmJS, Cosmos Kit, and Leap Social Login.

If you’re ready to go live with your Capsule integration, make sure to review our go-live checklist:

Go-Live Checklist

Review our go-live checklist to ensure you've configured all necessary settings before launching your Capsule integration.

​
Troubleshooting

If you encounter issues during the integration or usage of the Capsule Modal, here are some common problems and their solutions:

For a more comprehensive list of solutions, visit our troubleshooting guide:

Troubleshooting

Our troubleshooting guide provides solutions to common integration and usage problems.

​
Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our support team for assistance. To help us serve you better, include the following information in your support request:

  1. 1

    A detailed description of the problem you’re encountering.

  2. 2

    Any relevant error messages or logs.

  3. 3

    Steps to reproduce the issue.

  4. 4

    Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.

Was this page helpful?

WelcomeReact Native