Upgrade Guide

What's new in v3

• Support for Vue & Nuxt
• Simpler design and new theming mechanism
• More optimized multi platform wallet support
• Smaller bundle size
• New Explorer API integration
• Unified experience for iOS, Android and Desktop

Web3Modal v2 to v3 Upgrade Guide

This guide is useful for those that have used a previous Web3Modal V2 version and are looking to upgrade to V3.

Installation

React

To upgrade from Web3Modal v2 to v3 start by removing Web3Modal v2 dependencies @web3modal/ethereum and @web3modal/react, while keeping wagmi and viem installed. Now you can install Web3Modal v3 library

npm

npm install @web3modal/wagmi@3.5.7 wagmi@1.4.13 viem@1.21.4

Yarn

yarn add @web3modal/wagmi@3.5.7 wagmi@1.4.13 viem@1.21.4

Bun

bun add @web3modal/wagmi@3.5.7 wagmi@1.4.13 viem@1.21.4

pnpm

pnpm add @web3modal/wagmi@3.5.7 wagmi@1.4.13 viem@1.21.4

JavaScript

To upgrade from Web3Modal v2 to v3 start by removing Web3Modal v2 dependencies @web3modal/ethereum and @web3modal/html, while keeping @wagmi/core and viem installed. Now you can install Web3Modal v3 library

npm

npm install @web3modal/wagmi@3.5.7 @wagmi/core@1.4.13 viem@1.21.4

Yarn

yarn add @web3modal/wagmi@3.5.7 @wagmi/core@1.4.13 viem@1.21.4

Bun

bun add @web3modal/wagmi@3.5.7 @wagmi/core@1.4.13 viem@1.21.4

pnpm

pnpm add @web3modal/wagmi@3.5.7 @wagmi/core@1.4.13 viem@1.21.4

Implementation

React

You can start the Web3Modal configuration by using either the default or advanced mode.

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

note

Make sure to set your configuration outside React components to avoid unwanted rerenders.

Default

Start by importing createWeb3Modal, defaultWagmiConfig and wagmi packages

- import { EthereumClient, w3mConnectors, w3mProvider } from '@web3modal/ethereum'
- import { Web3Modal } from '@web3modal/react'
+ import { createWeb3Modal, defaultWagmiConfig } from '@web3modal/wagmi/react'

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

Then create wagmiConfig using defaultWagmiConfig function as shown below

const chains = [arbitrum, mainnet]
const projectId = 'YOUR_PROJECT_ID'

/* Create Wagmi Config */
- const { publicClient } = configureChains(chains, [w3mProvider({ projectId })])
- const wagmiConfig = createConfig({
-   autoConnect: true,
-   connectors: w3mConnectors({ projectId, chains }),
-   publicClient
- })
+ const metadata = {
+   name: 'Web3Modal',
+   description: 'Web3Modal Example',
+   url: 'https://web3modal.com',
+   icons: ['https://avatars.githubusercontent.com/u/37784886']
+ }

+ const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata })

Finally, pass wagmiConfig to createWeb3Modal

/* Call createWeb3Modal function */
- const ethereumClient = new EthereumClient(wagmiConfig, chains)
+ createWeb3Modal({ wagmiConfig, projectId, chains })

export default function App() {
  return (
    <>
      <WagmiConfig config={wagmiConfig}>
        <HomePage />
      </WagmiConfig>

-     <Web3Modal projectId={projectId} ethereumClient={ethereumClient} />
    </>
  )
}

Advanced

Start by importing createWeb3Modal, walletConnectProvider and wagmi packages

- import { EthereumClient, w3mConnectors, w3mProvider } from '@web3modal/ethereum'
- import { Web3Modal } from '@web3modal/react'
+ import { createWeb3Modal } from '@web3modal/wagmi/react'
+ import { walletConnectProvider } from '@web3modal/wagmi'

import { WagmiConfig, configureChains, createConfig } from 'wagmi'
import { mainnet } from 'viem/chains'
+ import { CoinbaseWalletConnector } from 'wagmi/connectors/coinbaseWallet'
+ import { InjectedConnector } from 'wagmi/connectors/injected'
+ import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'

Then create wagmiConfig using your own settings

// 1. Get projectId at https://cloud.walletconnect.com
const projectId = 'YOUR_PROJECT_ID'

// 2. Create wagmiConfig
- const { chains, publicClient } = configureChains([mainnet], [w3mProvider({ projectId })])
+ const { chains, publicClient } = configureChains([mainnet], [
+   walletConnectProvider({ projectId }),
+   publicProvider()
+ ])

- const wagmiConfig = createConfig({
-   autoConnect: true,
-   connectors: w3mConnectors({ projectId, chains }),
-   publicClient
- })
+ const metadata = {
+   name: 'Web3Modal',
+   description: 'Web3Modal Example',
+   url: 'https://web3modal.com',
+   icons: ['https://avatars.githubusercontent.com/u/37784886']
+ }

+ const wagmiConfig = createConfig({
+   autoConnect: true,
+   connectors: [
+     new WalletConnectConnector({ chains, options: { projectId, showQrModal: false, metadata } }),
+     new InjectedConnector({ chains, options: { shimDisconnect: true } }),
+     new CoinbaseWalletConnector({ chains, options: { appName: metadata.name } })
+   ],
+   publicClient
+ })

Finally, pass wagmi config to createWeb3Modal

/* Call createWeb3Modal function */
- const ethereumClient = new EthereumClient(wagmiConfig, chains)
+ createWeb3Modal({ wagmiConfig, projectId, chains })

export default function App() {
  return (
    <>
      <WagmiConfig config={wagmiConfig}>
        <HomePage />
      </WagmiConfig>

-     <Web3Modal projectId={projectId} ethereumClient={ethereumClient} />
    </>
  )
}

JavaScript

Start by importing Web3Modal and wagmi packages, then create wagmi config using your own settings or our default presets as shown below. Finally, pass wagmi config to Web3Modal as ethereumClient.

Default

Start by importing createWeb3Modal, defaultWagmiConfig and wagmi packages

- import { EthereumClient, w3mConnectors, w3mProvider } from '@web3modal/ethereum'
- import { Web3Modal } from '@web3modal/html'
+ import { createWeb3Modal, defaultWagmiConfig } from '@web3modal/wagmi/react'

import { configureChains, createConfig } from '@wagmi/core'
import { arbitrum, mainnet } from 'viem/chains'

Then create wagmiConfig using defaultWagmiConfig function as shown below

const chains = [arbitrum, mainnet]
const projectId = 'YOUR_PROJECT_ID'

/* Create Wagmi Config */
- const { publicClient } = configureChains(chains, [w3mProvider({ projectId })])
- const wagmiConfig = createConfig({
-   autoConnect: true,
-   connectors: w3mConnectors({ projectId, chains }),
-   publicClient
- })
+ const metadata = {
+   name: 'Web3Modal',
+   description: 'Web3Modal Example',
+   url: 'https://web3modal.com',
+   icons: ['https://avatars.githubusercontent.com/u/37784886']
+ }
+ const wagmiConfig = defaultWagmiConfig({ chains, projectId, appName: metadata.name })

Finally, pass wagmiConfig to createWeb3Modal

- const ethereumClient = new EthereumClient(wagmiConfig, chains)
+ createWeb3Modal({ wagmiConfig, projectId, chains })

Advanced

Start by importing Web3Modal, walletConnectProvider and wagmi packages

- import { EthereumClient, w3mConnectors, w3mProvider } from '@web3modal/ethereum'
- import { Web3Modal } from '@web3modal/react'
+ import { Web3Modal, walletConnectProvider } from '@web3modal/wagmi'

import { configureChains, createConfig } from '@wagmi/core'
import { mainnet } from 'viem/chains'
+ import { CoinbaseWalletConnector } from 'wagmi/connectors/coinbaseWallet'
+ import { InjectedConnector } from 'wagmi/connectors/injected'
+ import { WalletConnectConnector } from 'wagmi/connectors/walletConnect'

Then create wagmiConfig using your own settings

// 1. Get projectId at https://cloud.walletconnect.com
const projectId = 'YOUR_PROJECT_ID'

// 2. Create wagmiConfig
- const { chains, publicClient } = configureChains([mainnet], [w3mProvider({ projectId })])
+ const { chains, publicClient } = configureChains([mainnet], [
+   walletConnectProvider({ projectId }),
+   publicProvider()
+ ])

- const wagmiConfig = createConfig({
-   autoConnect: true,
-   connectors: w3mConnectors({ projectId, chains }),
-   publicClient
- })
+ const metadata = {
+   name: 'Web3Modal',
+   description: 'Web3Modal Example',
+   url: 'https://web3modal.com',
+   icons: ['https://avatars.githubusercontent.com/u/37784886']
+ }

+ const wagmiConfig = createConfig({
+   autoConnect: true,
+   connectors: [
+     new WalletConnectConnector({ chains, options: { projectId, showQrModal: false, metadata } }),
+     new InjectedConnector({ chains, options: { shimDisconnect: true } }),
+     new CoinbaseWalletConnector({ chains, options: { appName: metadata.name } })
+   ],
+   publicClient
+ })

Finally, pass wagmiConfig to createWeb3Modal

- const ethereumClient = new EthereumClient(wagmiConfig, chains)
+ createWeb3Modal({ wagmiConfig, projectId, chains })

Trigger the modal

React

- import { useWeb3Modal } from '@web3modal/react'
+ import { useWeb3Modal } from '@web3modal/wagmi/react'

function HomePage() {
  const { open } = useWeb3Modal()

  return <button onClick={() => open()}>Connect</button>
}

Learn more about Web3Modal v3 here

JavaScript

Use your own button with to open the modal

document.getElementById('my-button').addEventListener('click', () => {
-   web3modal.openModal()
+   modal.open()
})

<button id="my-button">Connect Wallet</button>

Learn more about Web3Modal v3 JavaScript here