Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

This guide will help you migrate from Web3Modal v5 using ethers to the latest Reown AppKit.

Find here all the upgrades guides:

Installation

To upgrade from Web3Modal v5 to Reown AppKit, start by removing the Web3Modal v5 dependency @web3modal/ethers.

npm uninstall @web3modal/ethers

Next, install the Reown AppKit packages.

npm install @reown/appkit @reown/appkit-adapter-ethers

Implementation

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers/react'
- import { arbitrum, mainnet } from 'viem/chains'

// Add the following imports
+ import { createAppKit } from '@reown/appkit/react'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
-createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
  createAppKit({
    adapters: [new EthersAdapter()],
    networks: [mainnet, arbitrum],
    metadata,
    projectId,
    features: {
      analytics: true,
    },
  });

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers/react'
- import { arbitrum, mainnet } from 'viem/chains'

// Add the following imports
+ import { createAppKit } from '@reown/appkit/react'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
-createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
  createAppKit({
    adapters: [new EthersAdapter()],
    networks: [mainnet, arbitrum],
    metadata,
    projectId,
    features: {
      analytics: true,
    },
  });

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from "@web3modal/ethers/vue";

// Add the following imports
+ import { createAppKit } from "@reown/appkit/vue";
+ import { arbitrum, mainnet } from "@reown/appkit/networks";
+ import { EthersAdapter } from "@reown/appkit-adapter-ethers";

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
- createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
 const modal = createAppKit({
 adapters: [new EthersAdapter()],
 networks: [mainnet, arbitrum],
 metadata,
 projectId,
 features: {
   analytics: true,
 }
})

Start by importing AppKit packages, then create EthersAdapter using your own settings or the default presets as shown below.

Import createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers'

// Add the following imports
+ import { createAppKit } from '@reown/appkit'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the existing Ethers Config as shown below
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
- const modal = createWeb3Modal({
  ethersConfig,
  projectId,
  enableAnalytics: true
})

// Add the following code lines
+ const modal = createAppKit({
  adapters: [new EthersAdapter()],
  networks: [mainnet, arbitrum],
  metadata,
  projectId,
  features: {
    analytics: true
  }
})

// Remove the following import
- import { useWeb3Modal } from '@web3modal/ethers/react'

// Add the following import
+ import { useAppKit } from '@reown/appkit/react'
function HomePage() {
  const { open } = useAppKit()
  return <button onClick={open}>Connect</button>
}

Learn more about Reown AppKit here

// Remove the following import
- import { useWeb3Modal } from '@web3modal/ethers/react'

// Add the following import
+ import { useAppKit } from '@reown/appkit/react'
function HomePage() {
  const { open } = useAppKit()
  return <button onClick={open}>Connect</button>
}

Learn more about Reown AppKit here

Use your own button to open the modal

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

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

Learn more about Reown AppKit JavaScript here

Use your own button to open the modal

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

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

Learn more about Reown AppKit JavaScript here

Properties

As you may have noticed, some of the properties of Web3Modal have changed as a consequence of the migration to Reown AppKit.

adapters

The adapters property is a new property that is an array of adapters that can be initialized.

networks

The chains property is now networks in Reown AppKit. You should import them from @reown/appkit/networks package instead of importing these networks from viem or other packages.

defaultNetwork

The defaultChain property is now defaultNetwork in Reown AppKit. This is a network object that specifies the default network for your Web3 app.

Utility Functions

The following methods are still available with the same nomenclature as before:

This returns the connected address.

It returns the active namespace’s address.

Example: You’ve initialized both the Wagmi and Solana adapters and connected to a dApp with an EVM-only wallet (e.g., Rainbow). In this case, the Solana adapter is still not connected. When your active network is one of the EVM chains, the address will return your wallet address. However, if you manually switch to the Solana network, the address will return undefined (unless you connect to a Solana wallet).

This returns the error values.

Returns the active network’s chainId

In versions prior to v5, which were single-chain, getChainId() returned a single type rather than multiple types:

@web3modal/wagmi (along with ethers and ethers5) returned number | undefined.
@web3modal/solana returned string | undefined.

Now, in Reown AppKit, since both chains can be connected simultaneously, the type definition is number | string | undefined.

This switches the active network to the different network being passed.

Unlike in v5, modal.switchNetwork takes the chain object as parameter rather than the chain id.

(v5) - switchNetwork(137) -> switches the chain to Polygon as we are passing Polygon’s chain id.
(Reown AppKit v1) - switchNetwork(polygon) -> polygon is imported from @reown/appkit/networks.

// Remove the following code line
modal.switchNetwork(137);

// Add the following code lines
import { polygon } from "@reown/appkit/networks";
modal.switchNetwork(polygon);

This returns if the selected network adapter is connected or not.

It returns the active namespace’s connection status as a boolean.

Example: You’ve initialized both the Wagmi and Solana adapters and connected to the dApp with an EVM-only wallet (e.g., Rainbow). In this case, the Solana adapter is still not connected. When you manually switch to the Solana network from the network selection list, you will see a disconnected state because the Solana adapter cannot use Rainbow’s connection. As a result, it will prompt you to connect with a Solana wallet.

This returns the active connection provider.

This returns the active connection provider type.

This is a listener that detects changes to the AppKit state, such as address, chainId, isConnected, provider, and providerType.

address - It returns the connected wallet address. The value returned is the same as modal.getAddress()
chainId - It returns the active network’s chainId . The value returned is the same as modal.getChainId()
isConnected - It returns if the selected network adapter is connected. The value returned is the same as modal.getIsConnected()
provider - It returns the active connection provider. The value returned is the same as modal.getWalletProvider()
providerType - It returns the active connection provider type. The value returned is the same as modal.getWalletProviderType()

The following methods and listeners are exactly the same and do not have any specific details related to the multiple chains feature.

modal.getState - it returns the modal state
- open - it returns boolean that indicates if the modal is open or not
- selectedNetworkId - it returns active network’s id
modal.subscribeState
modal.setThemeMode
modal.getThemeMode
modal.setThemeVariables
modal.getThemeVariables
modal.subscribeTheme
modal.getEvent
modal.subscribeEvents

On this page

Upgrade Guide
Web3Modal v5 to Reown Web AppKit | Ethers
Installation
Implementation
Trigger the modal
Properties
adapters
networks
defaultNetwork
Utility Functions
modal.getAddress()
modal.getError()
modal.getChainId()
modal.switchNetwork(network)
modal.getIsConnected()
modal.getWalletProvider()
modal.getWalletProviderType()
modal.subscribeProvider(callback)

Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

This guide will help you migrate from Web3Modal v5 using ethers to the latest Reown AppKit.

Find here all the upgrades guides:

Installation

To upgrade from Web3Modal v5 to Reown AppKit, start by removing the Web3Modal v5 dependency @web3modal/ethers.

npm uninstall @web3modal/ethers

Next, install the Reown AppKit packages.

npm install @reown/appkit @reown/appkit-adapter-ethers

Implementation

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers/react'
- import { arbitrum, mainnet } from 'viem/chains'

// Add the following imports
+ import { createAppKit } from '@reown/appkit/react'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
-createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
  createAppKit({
    adapters: [new EthersAdapter()],
    networks: [mainnet, arbitrum],
    metadata,
    projectId,
    features: {
      analytics: true,
    },
  });

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers/react'
- import { arbitrum, mainnet } from 'viem/chains'

// Add the following imports
+ import { createAppKit } from '@reown/appkit/react'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
-createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
  createAppKit({
    adapters: [new EthersAdapter()],
    networks: [mainnet, arbitrum],
    metadata,
    projectId,
    features: {
      analytics: true,
    },
  });

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

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

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

Start by importing createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from "@web3modal/ethers/vue";

// Add the following imports
+ import { createAppKit } from "@reown/appkit/vue";
+ import { arbitrum, mainnet } from "@reown/appkit/networks";
+ import { EthersAdapter } from "@reown/appkit-adapter-ethers";

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the following code line
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
- createWeb3Modal({ ethersConfig, projectId, chains })

// Add the following code lines
 const modal = createAppKit({
 adapters: [new EthersAdapter()],
 networks: [mainnet, arbitrum],
 metadata,
 projectId,
 features: {
   analytics: true,
 }
})

Start by importing AppKit packages, then create EthersAdapter using your own settings or the default presets as shown below.

Import createAppKit from @reown/appkit and the necessary chains from @reown/appkit/networks

// Remove the following imports
- import { createWeb3Modal, defaultConfig } from '@web3modal/ethers'

// Add the following imports
+ import { createAppKit } from '@reown/appkit'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { EthersAdapter } from '@reown/appkit-adapter-ethers'

Then, remove the defaultConfig function that is being imported from the Ethers package in your code.

const projectId = 'YOUR_PROJECT_ID'
const queryClient = new QueryClient()

const metadata = { //optional
    name: 'AppKit',
    description: 'AppKit Example',
    url: 'https://example.com',
    icons: ['https://avatars.githubusercontent.com/u/179229932']
}

// Remove the existing Ethers Config as shown below
- const ethersConfig = defaultConfig({ ... })

Finally, set up the EthersAdapter and pass the other parameters to createAppKit function.

// Remove the following code line
- const modal = createWeb3Modal({
  ethersConfig,
  projectId,
  enableAnalytics: true
})

// Add the following code lines
+ const modal = createAppKit({
  adapters: [new EthersAdapter()],
  networks: [mainnet, arbitrum],
  metadata,
  projectId,
  features: {
    analytics: true
  }
})

// Remove the following import
- import { useWeb3Modal } from '@web3modal/ethers/react'

// Add the following import
+ import { useAppKit } from '@reown/appkit/react'
function HomePage() {
  const { open } = useAppKit()
  return <button onClick={open}>Connect</button>
}

Learn more about Reown AppKit here

// Remove the following import
- import { useWeb3Modal } from '@web3modal/ethers/react'

// Add the following import
+ import { useAppKit } from '@reown/appkit/react'
function HomePage() {
  const { open } = useAppKit()
  return <button onClick={open}>Connect</button>
}

Learn more about Reown AppKit here

Use your own button to open the modal

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

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

Learn more about Reown AppKit JavaScript here

Use your own button to open the modal

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

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

Learn more about Reown AppKit JavaScript here

Properties

As you may have noticed, some of the properties of Web3Modal have changed as a consequence of the migration to Reown AppKit.

adapters

The adapters property is a new property that is an array of adapters that can be initialized.

networks

The chains property is now networks in Reown AppKit. You should import them from @reown/appkit/networks package instead of importing these networks from viem or other packages.

defaultNetwork

The defaultChain property is now defaultNetwork in Reown AppKit. This is a network object that specifies the default network for your Web3 app.

Utility Functions

The following methods are still available with the same nomenclature as before:

This returns the connected address.

It returns the active namespace’s address.

This returns the error values.

Returns the active network’s chainId

In versions prior to v5, which were single-chain, getChainId() returned a single type rather than multiple types:

@web3modal/wagmi (along with ethers and ethers5) returned number | undefined.
@web3modal/solana returned string | undefined.

Now, in Reown AppKit, since both chains can be connected simultaneously, the type definition is number | string | undefined.

This switches the active network to the different network being passed.

Unlike in v5, modal.switchNetwork takes the chain object as parameter rather than the chain id.

(v5) - switchNetwork(137) -> switches the chain to Polygon as we are passing Polygon’s chain id.
(Reown AppKit v1) - switchNetwork(polygon) -> polygon is imported from @reown/appkit/networks.

// Remove the following code line
modal.switchNetwork(137);

// Add the following code lines
import { polygon } from "@reown/appkit/networks";
modal.switchNetwork(polygon);

This returns if the selected network adapter is connected or not.

It returns the active namespace’s connection status as a boolean.

This returns the active connection provider.

This returns the active connection provider type.

This is a listener that detects changes to the AppKit state, such as address, chainId, isConnected, provider, and providerType.

address - It returns the connected wallet address. The value returned is the same as modal.getAddress()
chainId - It returns the active network’s chainId . The value returned is the same as modal.getChainId()
isConnected - It returns if the selected network adapter is connected. The value returned is the same as modal.getIsConnected()
provider - It returns the active connection provider. The value returned is the same as modal.getWalletProvider()
providerType - It returns the active connection provider type. The value returned is the same as modal.getWalletProviderType()

The following methods and listeners are exactly the same and do not have any specific details related to the multiple chains feature.

modal.getState - it returns the modal state
- open - it returns boolean that indicates if the modal is open or not
- selectedNetworkId - it returns active network’s id
modal.subscribeState
modal.setThemeMode
modal.getThemeMode
modal.setThemeVariables
modal.getThemeVariables
modal.subscribeTheme
modal.getEvent
modal.subscribeEvents

On this page

Upgrade Guide
Web3Modal v5 to Reown Web AppKit | Ethers
Installation
Implementation
Trigger the modal
Properties
adapters
networks
defaultNetwork
Utility Functions
modal.getAddress()
modal.getError()
modal.getChainId()
modal.switchNetwork(network)
modal.getIsConnected()
modal.getWalletProvider()
modal.getWalletProviderType()
modal.subscribeProvider(callback)

Migrate from Web3Modal v5 to Reown AppKit Solana

Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

Installation

Implementation

Properties

adapters

networks

defaultNetwork

Utility Functions

Cloud

Migrate from Web3Modal v5 to Reown AppKit Solana

Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

Installation

Implementation

Properties

adapters

networks

defaultNetwork

Utility Functions

​Upgrade Guide

​Web3Modal v5 to Reown Web AppKit | Ethers

​Installation

​Implementation

​Trigger the modal

​Properties

​adapters

​networks

​defaultNetwork

​Utility Functions

​modal.getAddress()

​modal.getError()

​modal.getChainId()

​modal.switchNetwork(network)

​modal.getIsConnected()

​modal.getWalletProvider()

​modal.getWalletProviderType()

​modal.subscribeProvider(callback)

Cloud

​Upgrade Guide

​Web3Modal v5 to Reown Web AppKit | Ethers

​Installation

​Implementation

​Trigger the modal

​Properties

​adapters

​networks

​defaultNetwork

​Utility Functions

​modal.getAddress()

​modal.getError()

​modal.getChainId()

​modal.switchNetwork(network)

​modal.getIsConnected()

​modal.getWalletProvider()

​modal.getWalletProviderType()

​modal.subscribeProvider(callback)

Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

Installation

Implementation

Trigger the modal

Properties

adapters

networks

defaultNetwork

Utility Functions

modal.getAddress()

modal.getError()

modal.getChainId()

modal.switchNetwork(network)

modal.getIsConnected()

modal.getWalletProvider()

modal.getWalletProviderType()

modal.subscribeProvider(callback)

Upgrade Guide

Web3Modal v5 to Reown Web AppKit | Ethers

Installation

Implementation

Trigger the modal

Properties

adapters

networks

defaultNetwork

Utility Functions

modal.getAddress()

modal.getError()

modal.getChainId()

modal.switchNetwork(network)

modal.getIsConnected()

modal.getWalletProvider()

modal.getWalletProviderType()

modal.subscribeProvider(callback)