Skip to main content


Web3Modal SDK has support for Wagmi, Ethers v5 and Ethers v6. Choose one of these ethereum libraries to get started.


These steps are specific to Next.js app router.


npm install @web3modal/wagmi wagmi viem

Don't have a project ID?

Head over to WalletConnect Cloud and create a new project now!

Get startedcloud illustration


You can start Web3Modal configuration using either default or custom mode.

Default mode will implement WalletConnect, Browser Wallets (injected) and Coinbase options in addition to Wagmi's public provider and WalletConnect's provider.

Create a new file called context/Web3Modal.tsx or context/Web3Modal.jsx (outside your app directory) and set up the following configuration, making sure that all functions are called outside any React component to avoid unwanted rerenders.

"use client";

import { createWeb3Modal, defaultWagmiConfig } from '@web3modal/wagmi/react'

import { WagmiConfig } from 'wagmi'
import { arbitrum, mainnet } from 'viem/chains'

// 1. Get projectId at
const projectId = 'YOUR_PROJECT_ID'

// 2. Create wagmiConfig
const metadata = {
name: 'Web3Modal',
description: 'Web3Modal Example',
url: '',
icons: ['']

const chains = [mainnet, arbitrum]
const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata })

// 3. Create modal
createWeb3Modal({ wagmiConfig, projectId, chains })

export function Web3Modal({ children }) {
return <WagmiConfig config={wagmiConfig}>{children}</WagmiConfig>;

Next, in your app/layout.tsx or app/layout.jsx file, import the custom Web3Modal component.

import "./globals.css";

import { Web3Modal } from "../context/Web3Modal";

export const metadata = {
title: "Web3Modal",
description: "Web3Modal Example",

export default function RootLayout({ children }) {
return (
<html lang="en">

Trigger the modal

To open Web3Modal you can use our default web components or build your own logic using Web3Modal hooks.

export default function ConnectButton() {
return <w3m-button />

Learn more about the Web3Modal web components here


Web components are global html elements that don't require importing.

Smart Contract Interaction

import { useContractRead } from 'wagmi'
import { USDTAbi } from '../abi/USDTAbi'

const USDTAddress = '0x...'

function App() {
const { data, isError, isLoading } = useContractRead({
address: USDTAddress,
abi: USDTAbi,
functionName: 'symbol',

Read more about Wagmi hooks for smart contract interaction here.

Extra configuration

Next.js relies on SSR. This means some specific steps are required to make Web3Modal work properly.

  • Add the following code in the next.config.js file
// Path: next.config.js
const nextConfig = {
webpack: config => {
config.externals.push('pino-pretty', 'lokijs', 'encoding')
return config
  • If SWCMinify is flagged, it must be false in the next.config.js file
  • If you are using Wagmi, dynamic imports or supressHydrationWarning are recommended tro prevent Hydration mismatch errors