Upgrade Guide
AppKit v5 to Reown AppKit Upgrade Guide
This guide will help you migrate from AppKit v5 to the latest Reown AppKit.
Installation
- React
- Vue
- JavaScript
To upgrade from AppKit v5 to Reown AppKit start by removing AppKit v5 dependencies @web3modal/ethereum
and @web3modal/react
. Now you can install AppKit library and update Wagmi
and Viem
.
- npm
- Yarn
- Bun
- pnpm
npm install @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
yarn add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
bun add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
pnpm add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
To upgrade from AppKit v5 to Reown AppKit start by removing AppKit v5 dependencies @web3modal/ethereum
and @web3modal/react
. Now you can install AppKit library and update @wagmi/core
and Viem
.
- npm
- Yarn
- Bun
- pnpm
npm install @reown/appkit @reown/appkit-adapter-wagmi
yarn add @reown/appkit @reown/appkit-adapter-wagmi
bun add @reown/appkit @reown/appkit-adapter-wagmi
pnpm add @reown/appkit @reown/appkit-adapter-wagmi
To upgrade from AppKit v5 to Reown AppKit start by removing AppKit v5 dependencies @web3modal/ethereum
and @web3modal/vue
. Now you can install AppKit library and update Wagmi
and Viem
.
- npm
- Yarn
- Bun
- pnpm
npm install @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
yarn add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
bun add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
pnpm add @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
Implementation
- React
- Vue
- JavaScript
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 Wagmi's public clients and 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
- import { createWeb3Modal } from '@web3modal/wagmi/react'
- import { defaultWagmiConfig } from '@web3modal/wagmi/react/config'
- import { WagmiConfig } from 'wagmi'
- import { arbitrum, mainnet } from 'viem/chains'
+ import { createAppKit } from '@reown/appkit/react'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
Then create wagmiAdapter
using WagmiAdapter
function as shown below
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 Wagmi Config */
+ const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata })
/* Create the Wagmi adapter */
+ const wagmiAdapter = new WagmiAdapter({
networks: [mainnet, arbitrum],
projectId
})
Finally, pass wagmiAdapter
(optional) and other parameters to createAppKit
- createWeb3Modal({ wagmiConfig, projectId, chains })
// import { createAppKit } from '@reown/appkit/react'
+ createAppKit({
adapters: [wagmiAdapter],
networks: [mainnet, arbitrum],
metadata: metadata,
projectId,
features: {
analytics: true,
}
})
export default function App() {
return (
<>
- <WagmiConfig config={wagmiConfig}>
+ <WagmiConfig config={wagmiAdapter.wagmiConfig}>
<QueryClientProvider client={queryClient}>
<HomePage />
</QueryClientProvider>
</WagmiConfig>
</>
)
}
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 Wagmi's public clients and 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
import { createWeb3Modal } from '@web3modal/wagmi/vue'
import { defaultWagmiConfig } from '@web3modal/wagmi/react/config'
import { WagmiConfig } from 'wagmi'
import { arbitrum, mainnet } from 'viem/chains'
import { createAppKit } from '@reown/appkit/vue'
import { arbitrum, mainnet } from '@reown/appkit/networks'
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
Then create wagmiAdapter
using WagmiAdapter
function as shown below
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 Wagmi Config */
- const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata })
/* Create the Wagmi adapter */
+ const wagmiAdapter = new WagmiAdapter({
networks: [mainnet, arbitrum],
projectId
})
Finally, pass wagmiAdapter
(optional) and other parameters to createAppKit
- createWeb3Modal({ wagmiConfig, projectId, chains })
// import { createAppKit } from '@reown/appkit/vue'
+ const modal = createAppKit({
adapters: [wagmiAdapter],
networks: [mainnet, arbitrum],
metadata: metadata,
projectId,
features: {
analytics: true,
}
})
export default function App() {
return (
<>
- <WagmiConfig config={wagmiConfig}>
+ <WagmiConfig config={wagmiAdapter.wagmiConfig}>
<QueryClientProvider client={queryClient}>
<HomePage />
</QueryClientProvider>
</WagmiConfig>
</>
)
}
Start by importing AppKit packages, then create wagmiAdapter using your own settings or the default presets as shown below. Finally, pass wagmiAdapter to AppKit as one of the adapters.
Import createAppKit
from @reown/appkit
and the necessary chains from @reown/appkit/networks
- import { createWeb3Modal, defaultWagmiConfig } from '@web3modal/wagmi/react'
- import { createConfig } from '@wagmi/core'
- import { arbitrum, mainnet } from 'viem/chains'
+ import { createAppKit } from '@reown/appkit'
+ import { arbitrum, mainnet } from '@reown/appkit/networks'
+ import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
Then create wagmiAdapter
using WagmiAdapter
function as shown below
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 Wagmi Config */
- const wagmiConfig = defaultWagmiConfig({ chains, projectId, metadata })
/* Create the Wagmi adapter */
+ const wagmiAdapter = new WagmiAdapter({
networks: [mainnet, arbitrum],
projectId
})
Finally, pass wagmiAdapter
(optional) and other parameters to createAppKit
.
- const modal = createWeb3Modal({
wagmiConfig,
projectId,
enableAnalytics: true
})
// import { createAppKit } from '@reown/appkit'
+ const modal = createAppKit({
adapters: [wagmiAdapter],
networks: [mainnet, arbitrum],
metadata: metadata,
projectId,
features: {
analytics: true
}
})
Trigger the modal
- React
- Vue
- JavaScript
- import { useWeb3Modal } from '@web3modal/wagmi/react'
+ 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 with 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 with 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:
modal.getAddress()
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).
modal.getError()
This returns the error values.
modal.getChainId()
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) returnednumber | undefined
.@web3modal/solana
returnedstring | undefined
.
Now, in Reown AppKit, since both chains can be connected simultaneously, the type definition is number | string | undefined
.
modal.switchNetwork(network)
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
.
switchNetwork(137)
import { polygon } from '@reown/appkit/networks'
switchNetwork(polygon)
modal.getIsConnected()
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.
modal.getWalletProvider()
This returns the active connection provider.
modal.getWalletProviderType()
This returns the active connection provider type.
modal.subscribeProvider(callback)
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 asmodal.getAddress()
chainId
- It returns the active network’schainId
. The value returned is the same asmodal.getChainId()
isConnected
- It returns if the selected network adapter is connected. The value returned is the same asmodal.getIsConnected()
provider
- It returns the active connection provider. The value returned is the same asmodal.getWalletProvider()
providerType
- It returns the active connection provider type. The value returned is the same asmodal.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 stateopen
- it returns boolean that indicates if the modal is open or notselectedNetworkId
- it returns active network’s id
modal.subscribeState
modal.setThemeMode
modal.getThemeMode
modal.setThemeVariables
modal.getThemeVariables
modal.subscribeTheme
modal.getEvent
modal.subscribeEvents