​
Introduction

Capsule works as an easy add-on to Blocknative’s Web3-Onboard library. If you’re already using Web3-Onboard, you can add Capsule as an option in just a few lines of code.

This guide provides a step-by-step process to integrate Capsule with Web3-Onboard, from installation to configuration and usage within a React project.

​
Prerequisites

Ensure you have the following installed:

  • Node.js
  • npm or yarn

​
Step 1: Installation

First, you need to install the required packages. You can choose your preferred package manager:

​
Step 2: Configuration

Next, set up the Web3-Onboard and Capsule modules in your React project.

​
Initializing Web3-Onboard

Create a new file onboard.ts in your project root and add the following code:

onboard.ts
import Onboard from '@web3-onboard/core';
import injectedModule from '@web3-onboard/injected-wallets';
import capsuleModule, { Environment, OAuthMethod, Theme } from '@web3-onboard/capsule';

// Initialize the Capsule module with CapsuleInitOptions
const capsule = capsuleModule({
  environment: Environment.BETA, // Use Environment.PROD for production
  apiKey: 'YOUR_API_KEY',
  modalProps: {
    theme: Theme.dark,
    oAuthMethods: [OAuthMethod.GOOGLE, OAuthMethod.TWITTER],
    logo: '/my_logo.png', // Your logo (supports .png, .jpg, .svg)
  },
  constructorOpts: {
    emailTheme: 'light',
    emailPrimaryColor: 'pink',
    portalBackgroundColor: '#5e5656',
    portalPrimaryButtonColor: '#ff6700',
    portalTextColor: '#ffffff',
  },
  walletIcon: async () => (await import('./my-app-icon.js')).default,
  walletLabel: 'Sign In with Email',
});

// Initialize Onboard with the Capsule wallet
const onboard = Onboard({
  apiKey: 'YOUR_BLOCKNATIVE_API_KEY',
  wallets: [capsule, injectedModule()],
  chains: [
    //
  ],
});

export default onboard;

​
Step 3: Usage in a React Component

Now, you can use the initialized onboard instance in your React components. For example, in App.js:

connectButton.tsx
import React from 'react';
import { init, useConnectWallet } from '@web3-onboard/react';
import { ethers } from 'ethers';
import onboard from './onboard';

function App() {
  const [{ wallet, connecting }, connect, disconnect] = useConnectWallet();

  // Create an ethers provider
  let ethersProvider;
  if (wallet) {
    ethersProvider = new ethers.providers.Web3Provider(wallet.provider, 'any');
  }

  return (
    <div>
      <button
        disabled={connecting}
        onClick={() => (wallet ? disconnect(wallet) : connect())}>
        {connecting ? 'Connecting...' : wallet ? 'Disconnect' : 'Connect'}
      </button>
    </div>
  );
}

export default App;

​
Additional Features

​
Using Web3OnboardProvider

To manage global state more effectively, wrap your application in Web3OnboardProvider:

App.tsx
import { Web3OnboardProvider } from '@web3-onboard/react';
import onboard from './onboard';

function MyApp({ Component, pageProps }) {
  return (
    <Web3OnboardProvider web3Onboard={onboard}>
      <Component {...pageProps} />
    </Web3OnboardProvider>
  );
}

export default MyApp;

​
Using Hooks

Leverage Web3-Onboard hooks such as useConnectWallet, useSetChain, useNotifications, useWallets, and useAccountCenter to interact with wallets and manage the user experience. These hooks provide a streamlined way to handle wallet connections, chain settings, notifications, wallet state, and account center management.

For more details on these hooks and how to implement them, refer to the Block Native Web3-Onboard documentation.

​
Final Steps

By following these steps, you have successfully integrated Capsule with Blocknative’s Web3-Onboard library. This setup allows you to provide a seamless onboarding experience for your users, leveraging the power of Capsule’s secure, portable, and user-friendly wallets.

For more detailed information on customizations, check out the following guides:

Customization Guide

Learn how to customize Capsule for your needs

Signing Transactions

Signing with ethers.js, wagmi, and viem

​
Troubleshooting and Support

If you encounter any issues or have questions, please refer to the documentation or reach out to our support team.

Was this page helpful?

WagmiRainbowKit Integration