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:

const web3Modal = new 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:

const web3Modal = new 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/core'
import { CoinbaseWalletConnector } from '@wagmi/core/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.

const web3Modal = new 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.

const web3Modal = new 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'
  }
})