Web3-Onboard
This tutorial is a step-by-step guide on how to integrate a wallet such as Phantom into your dApp using the Web3-Onboard library. Web3-Onboard is an EVM wallet library that supports Phantom on Ethereum and Polygon.
We will be going through step by step how to go from zero to a fully integrated Web3-Onboard button. If you already have a dApp that you are trying to integrate Phantom in, you can use our project as reference. At the end of this guide, your adapter will look like this:

The Web3-Onboard modal that shows after a user presses "connect"
- Node version >=16.12.0
- A text editor/IDE (such as VSCode)
- Some Knowledge of React
To create a new React application using Vite, run the following command in your terminal:
yarn create vite
- 1.This will ask you for a project name. Provide it a name here. For purposes of this tutorial I used "Web3-onboard-Sandbox".
- 2.It will then ask you to select a framework. Select "React" here.
- 3.Next it will ask for a variant. Select "Typescript" here.
Now change directory into your project and run:
yarn install
And make sure your app runs by running the command:
yarn dev
Before moving forward, we're going to configure Vite to recognize the
window.ethereum
object. Since we are in Typescript if we try to use window.ethereum
without first doing this step, we will get a type error and be unable to compile our project.open the
vite-env.d.ts
file in the src
directory.It should look like this:
/// <reference types="vite/client" />
All you need to do is extend the
Window
interface. To do so modify the vite-env.d.ts
file to look like so:/// <reference types="vite/client" />
interface Window {
ethereum: any;
}
Now whenever we reference
window.ethereum
, we will not encounter any type errors.With your app running, we can now move onto the Web3-Onboard specific pieces.
To install the appropriate package, run the following:
yarn add @web3-onboard/react @web3-onboard/phantom
Now you can use the web3-onboard package in your project and integrate Phantom as a wallet in the modal.
First we will need to import the packages into our project. At the top of the
App.tsx
file add these two lines:import { init, useConnectWallet } from "@web3-onboard/react";
import phantomModule from "@web3-onboard/phantom";
Next, we will can initialize the modal by calling the init hook. You can add this code to the project between your imports and your
App
component.const phantom = phantomModule();
init({
wallets: [phantom],
chains: [
{
id: "0x1",
token: "ETH",
label: "Ethereum Mainnet",
rpcUrl:
"https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY_HERE",
},
]
});
Here you can see that we call the
init
hook that we imported, and provide the phantomModule
to an array of wallets
. Here you can also specify which chains your dapp supports.Each chain requires an
id
, token
, label
, and rpcUrl
. Phantom currently supports Polygon, Ethereum Mainnet, Goerli, and Mumbai.You can add as many chains as you would like. There are many configuration options that Web3-Onboard provides you. To see a full list of the different options you can check out their documentation here. You can customize your theme, i18n options, app metadata, realtime app notifications, and more.
With this bit of configuration out of the way we only need to add the button that will call the modal to the forefront of the screen to connect our wallet.
In your
App
component, you will utilize the useConnectWallet
hook that you imported earlier.Add this to the first line inside your component:
const [{ wallet, connecting }, connect, disconnect] = useConnectWallet();
This gives you the
connect
and disconnect
functions that we will attach to our button, as well as the wallet
and connecting
keys in an object that allow us to track state of various wallets and connection statuses.We now have everything we need to add the actual UI. You can place this block in place of the basic counter that comes in the Vite starter.
<button disabled={connecting} onClick={() => (wallet ? disconnect(wallet) : connect())}>
{connecting ? 'connecting' : wallet ? 'disconnect' : 'connect'}
</button>
If you save your project you should now have working connect button that displays the Phantom wallet button. Clicking on it will establish a connection to the dapp.
Here's what it will look like:

The landing page of our application

The Web3-Onboard modal that shows after a user presses "connect"
Web3-Onboard provides quite a lot out of the gate with very little work on your end as a developer. We hope that you enjoyed this guide.
If you got lost along the way do not worry. You can find the source code here to double check your work.
Last modified 3mo ago