React & Web

This guide will walk you through the process of integrating the Capsule Modal into your web application, providing a seamless way to manage user authentication and wallets.

​

Prerequisites

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

​

Installing Dependencies

In this section, you’ll install the Capsule React SDK, which is the core dependency needed to integrate Capsule into your web application.

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

​

Setting Up the Capsule SDK

Now that you’ve installed the necessary dependencies, let’s set up the Capsule SDK. This will involve creating a client instance, setting up polyfills, and integrating the Capsule Modal into your application.

​

Creating a Capsule Client Instance

First, create a Capsule client instance. This instance will be used to interact with the Capsule SDK and manage the authentication flow.

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.

​

Setting Up Polyfills

Depending on your target environment, you may need to set up polyfills for certain features that Capsule relies on. This step ensures that all required functionalities are supported in your application.

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.

​

Integrating the Capsule Modal

Now, integrate the Capsule Modal into your React component by importing the CapsuleModal component from the Capsule SDK, adding a button to trigger the modal, and handling the modal’s state.

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.

import dynamic from "next/dynamic";

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

​

Customizing the Capsule Modal

To provide the best experience for your users, you can customize the appearance and behavior of the Capsule Modal to match your application’s branding.

When rendering the CapsuleModal component, you can pass props to customize its appearance and behavior. This allows you to adjust the look and feel of the modal to align with your application’s branding.

<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 CapsuleModalProps, refer to the customization guide:

​

Examples

For practical implementation of the Capsule SDK in React applications, explore our example repository. This repository contains real-world examples to help you get started.

​

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.

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

​

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:

​

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your 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.