Skip to main content

Custom Wallets

caution

This documentation is for Web3Modal v2. You can find Web3Modal v3 docs here

Web3Modal includes wallets from 3 sources: WalletConnect explorer, wagmi connectors and manually defined wallets. Below are defaults for each source:

  1. All WalletConnect explorer wallets that satisfy your options
  2. When using w3mConnectors helper, modal includes WalletConnectConnector and InjectedConnector
  3. No manual wallets are defined by default

Wallets are ordered with following priority: wagmi connectors, manual wallets, explorer wallets.

Custom explorer wallets​

You can manage wallets fetched from explorer via explorerRecommendedWalletIds and explorerExcludedWalletIds options to prioritize, include or exclude them. To fully disable explorer wallets, use enableExplorer options.

You can get all wallet id's from WalletConnect explorer (click copy icon on chosen wallets).

Below is an example of how to prioritize MetaMask, Rainbow and TrustWallet in that specific order:

<Web3Modal
explorerRecommendedWalletIds={[
'c57ca95b47569778a828d19178114f4db188b89b763c899ba0be274e97267d96',
'1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369',
'4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0'
]}
/>

Now, these wallets will show up first in specified order. If you want to exclude some or all other wallets, you can combine above with explorerExcludedWalletIds option:

<Web3Modal
explorerRecommendedWalletIds={[
'c57ca95b47569778a828d19178114f4db188b89b763c899ba0be274e97267d96',
'1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369',
'4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0'
]}
explorerExcludedWalletIds="ALL"
/>

Custom wagmi connectors​

You can add any wagmi connector as you normally would in wagmi's createConfig function. However, for Web3Modal to work correctly WalletConnectConnector is required. Below is a simplified example of how to use CoinbaseWalletConnector together with defaults from w3mConnectors helper:

import { createConfig } from 'wagmi'
import { CoinbaseWalletConnector } from 'wagmi/connectors/coinbaseWallet'
import { w3mConnectors } from '@web3modal/ethereum'

const wagmiConfig = createConfig({
connectors: [
...w3mConnectors({
/* ... */
}),
new CoinbaseWalletConnector({
/* ... */
})
]
})

Custom manual wallets​

If your WalletConnect enabled wallet is not present in WalletConnect explorer or is still pending approval, you can add it manually via mobileWallets and desktopWallets options.

<Web3Modal
mobileWallets={[
{
id: 'customMobileWallet',
name: 'Custom Mobile Wallet',
links: {
native: 'customMobileWallet://',
universal: 'https://customMobileWallet.com'
}
}
]}
desktopWallets={[
{
id: 'customDesktopWallet',
name: 'Custom Desktop Wallet',
links: {
native: 'customDesktopWallet://',
universal: 'https://web.customDesktopWallet.com'
}
}
]}
/>

Custom wallet images​

If your wallet's logo is not supported by Web3Modal or you want to override default one, you can use walletImages option.

<Web3Modal
walletImages={{
// Override explorer wallet image
c57ca95b47569778a828d19178114f4db188b89b763c899ba0be274e97267d96:
'https://example.com/metamask.png',

// Override wagmi connector image (refer to wagmi to find id)
coinbaseWallet: 'https://example.com/coinbaseWallet.png',

// Override manual wallet image
customMobileWallet: 'https://example.com/customMobileWallet.png'
}}
/>