Skip to main content


Web3Modal SDK has support for Wagmi 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 @tanstack/react-query

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 the WalletConnect's provider.

Create a new file called config/index.tsx or config/index.jsx (outside your app directory) and set up the following configuration

import { defaultWagmiConfig } from '@web3modal/wagmi/react/config'

import { cookieStorage, createStorage } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

// Get projectId at
export const projectId = process.env.NEXT_PUBLIC_PROJECT_ID

if (!projectId) throw new Error('Project ID is not defined')

const metadata = {
name: 'Web3Modal',
description: 'Web3Modal Example',
url: '', // origin must match your domain & subdomain
icons: ['']

// Create wagmiConfig
export const config = defaultWagmiConfig({
chains: [mainnet, sepolia], // required
projectId, // required
metadata, // required
ssr: true,
storage: createStorage({
storage: cookieStorage
enableWalletConnect: true, // Optional - true by default
enableInjected: true, // Optional - true by default
enableEIP6963: true, // Optional - true by default
enableCoinbase: true, // Optional - true by default
...wagmiOptions // Optional - Override createConfig parameters

Notice that defaultWagmiConfig is now imported from '@web3modal/wagmi/react/config'

Create another file called context/index.tsx or context/index.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 React, { ReactNode } from 'react'
import { config, projectId } from '@/config'

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

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

import { State, WagmiProvider } from 'wagmi'

// Setup queryClient
const queryClient = new QueryClient()

if (!projectId) throw new Error('Project ID is not defined')

// Create modal
wagmiConfig: config,
enableAnalytics: true // Optional - defaults to your Cloud configuration

export function ContextProvider({
}: {
children: ReactNode
initialState?: State
}) {
return (
<WagmiProvider config={config} initialState={initialState}>
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>

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

import './globals.css'
import type { Metadata } from 'next'
import { headers } from 'next/headers'

import { cookieToInitialState } from 'wagmi'

import { config } from '@/config'
import { ContextProvider } from '@/context'

export const metadata: Metadata = {
title: 'Create Next App',
description: 'Generated by create next app'

export default function RootLayout({
}: Readonly<{
children: React.ReactNode
}>) {
const initialState = cookieToInitialState(config, headers().get('cookie'))
return (
<html lang="en">
<ContextProvider initialState={initialState}>{children}</ContextProvider>

createWeb3Modal must be called inside a client file, apart from Wagmi's configuration.

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 { useReadContract } from 'wagmi'
import { USDTAbi } from '../abi/USDTAbi'

const USDTAddress = '0x...'

function App() {
const result = useReadContract({
abi: USDTAbi,
address: USDTAddress,
functionName: 'totalSupply'

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