Skip to main content
This guide provides practical examples for configuring your walletList to achieve common desired wallet connection setups. Each recipe includes the configuration code and explains when to use it.
The walletList controls which wallet options appear in Privy’s connection modal and in what order. For detailed API reference, see Configure wallet options.

​
Quick Decision Guide

What do you want to show users?
  • Show ALL WalletConnect wallets (100+) → Use wallet_connect
  • Show a QR code for Ethereum wallets → Use wallet_connect_qr
  • Show a QR code for Solana wallets → Use wallet_connect_qr_solana
  • Show only specific wallets → List them explicitly (e.g., ['phantom', 'metamask'])
  • Show all detected browser extensions → Use detected_ethereum_wallets / detected_solana_wallets
Use case: Standard Ethereum app with popular wallet options plus WalletConnect fallback 
<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'metamask',
        'coinbase_wallet',
        'rainbow',
        'detected_ethereum_wallets',
        'wallet_connect_qr'
      ],
      walletChainType: 'ethereum-only'
    }
  }}
>
  {children}
</PrivyProvider>
What users see:
  1. MetaMask (if installed, shown first)
  2. Coinbase Wallet
  3. Rainbow
  4. Any other detected Ethereum browser extensions (alphabetically)
  5. WalletConnect button (shows QR code when clicked)
Best for:
  • Ethereum-focused applications
  • Desktop users with browser extensions
  • Apps that want to support mobile wallets via QR codes

​
Recipe 2: Solana Wallets Only

Use case: Solana-focused application with popular Solana wallets 
import {toSolanaWalletConnectors} from '@privy-io/react-auth/solana';

const solanaConnectors = toSolanaWalletConnectors({
  shouldAutoConnect: true
});

<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'phantom',
        'solflare',
        'backpack',
        'detected_solana_wallets',
        'wallet_connect_qr_solana'
      ],
      walletChainType: 'solana-only'
    },
    externalWallets: {
      solana: {
        connectors: solanaConnectors
      }
    }
  }}
>
  {children}
</PrivyProvider>;
Required for Solana: You must configure externalWallets.solana.connectors and set walletChainType to 'solana-only' or 'ethereum-and-solana' for Solana wallets to appear.
What users see:
  1. Phantom (prioritized first)
  2. Solflare
  3. Backpack
  4. Any other detected Solana browser extensions
  5. WalletConnect button for Solana wallets
Best for:
  • Solana-only applications
  • NFT marketplaces on Solana
  • Solana DeFi applications

​
Recipe 3: Multi-Chain (Ethereum + Solana)

Use case: Cross-chain application supporting both Ethereum and Solana 
import {toSolanaWalletConnectors} from '@privy-io/react-auth/solana';

const solanaConnectors = toSolanaWalletConnectors({
  shouldAutoConnect: true
});

<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'phantom', // Multi-chain (shown with badge)
        'metamask', // Ethereum only
        'solflare', // Solana only (shown with badge)
        'coinbase_wallet', // Ethereum only
        'detected_ethereum_wallets',
        'detected_solana_wallets',
        'wallet_connect_qr', // Ethereum WalletConnect
        'wallet_connect_qr_solana' // Solana WalletConnect
      ],
      walletChainType: 'ethereum-and-solana'
    },
    externalWallets: {
      solana: {
        connectors: solanaConnectors
      }
    }
  }}
>
  {children}
</PrivyProvider>;
What users see:
  • Both Ethereum and Solana wallets in one list
  • Solana wallets display with a “Solana” badge
  • Two separate WalletConnect options (one for each chain)
Best for:
  • Cross-chain applications
  • Portfolio tracking apps
  • Multi-chain DeFi platforms
When walletChainType is set to 'ethereum-and-solana', Privy automatically adds badges to Solana wallets to help users distinguish between chain types.

​
Recipe 4: Minimal Setup - Just Phantom and WalletConnect

Use case: Solana app that primarily uses Phantom with WalletConnect fallback 
import {toSolanaWalletConnectors} from '@privy-io/react-auth/solana';

const solanaConnectors = toSolanaWalletConnectors({
  shouldAutoConnect: true
});

<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: ['phantom', 'wallet_connect_qr_solana'],
      walletChainType: 'solana-only'
    },
    externalWallets: {
      solana: {
        connectors: solanaConnectors
      }
    }
  }}
>
  {children}
</PrivyProvider>;
What users see:
  • Only Phantom and WalletConnect options
  • Clean, minimal UI
  • No other wallet options displayed
Best for:
  • Apps with strong Phantom user base
  • Simplified onboarding flows
  • Mobile-first Solana applications
Warning: Users with other wallets (like Solflare or Backpack) won’t see connection options unless they use WalletConnect.

​
Recipe 5: Show All WalletConnect Registry Wallets

Use case: Maximum wallet compatibility - show every WalletConnect-supported wallet 
<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'metamask',
        'coinbase_wallet',
        'rainbow',
        'wallet_connect' // Shows 100+ wallets from registry
      ],
      walletChainType: 'ethereum-only'
    }
  }}
>
  {children}
</PrivyProvider>
wallet_connect shows 100+ wallets! This entry displays ALL wallets from the WalletConnect registry as individual, searchable options. If you want a simple QR code instead, use wallet_connect_qr.
What users see:
  • MetaMask, Coinbase Wallet, and Rainbow at the top
  • Followed by a long, searchable list of 100+ WalletConnect-supported wallets
  • Each wallet has its own connection button
Best for:
  • Apps needing maximum wallet compatibility
  • Desktop applications where users browse wallet options
  • Supporting niche or regional wallets
Not recommended for:
  • Mobile-first applications (UI becomes cluttered)
  • Simple onboarding flows
  • Apps with specific wallet preferences

​
Recipe 6: Desktop-Optimized with Auto-Detection

Use case: Desktop app that auto-detects all installed browser extensions 
<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: ['detected_ethereum_wallets', 'detected_solana_wallets', 'wallet_connect'],
      walletChainType: 'ethereum-and-solana'
    },
    externalWallets: {
      solana: {
        connectors: toSolanaWalletConnectors()
      }
    }
  }}
>
  {children}
</PrivyProvider>
What users see:
  1. All detected browser extensions (both Ethereum and Solana)
  2. Full WalletConnect registry for any wallet not installed
  3. Completely dynamic wallet list based on what’s installed
Best for:
  • Desktop-focused applications
  • Power users with multiple wallets installed
  • Maximum flexibility without manual configuration
Note: Wallets aren’t injected in mobile web browser environments, with the exception of the in-app browser for a few wallets (see In-App Browsers section). Thus, detected_*_wallets will show empty in mobile environments. Consider adding specific wallet names (like 'metamask', 'phantom') for mobile support.

​
Recipe 7: Prioritize Specific Wallet + Show Others

Use case: Promote a specific wallet but still support others 
import {toSolanaWalletConnectors} from '@privy-io/react-auth/solana';

const solanaConnectors = toSolanaWalletConnectors({
  shouldAutoConnect: true
});

<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'phantom', // Always shown first (even if detected)
        'backpack', // Shown second (even if detected)
        'detected_ethereum_wallets',
        'detected_solana_wallets'
      ],
      walletChainType: 'ethereum-and-solana'
    },
    externalWallets: {
      solana: {
        connectors: solanaConnectors
      }
    }
  }}
>
  {children}
</PrivyProvider>;
How ordering works:
  • Phantom always appears first
  • Backpack always appears second
  • Other detected wallets appear after, alphabetically
  • If Phantom is detected, it appears at position 1 (not duplicated in detected list)
Best for:
  • Apps with wallet partnerships
  • Promoting recommended wallets
  • Maintaining flexibility while guiding users

​
Recipe 8: WalletConnect Fallback for Unlisted Wallets

Use case: Support specific wallets but provide fallback for others 
<PrivyProvider
  appId="your-app-id"
  config={{
    appearance: {
      walletList: [
        'metamask',
        'rainbow',
        'coinbase_wallet',
        'wallet_connect' // Fallback for any other wallet
      ],
      walletChainType: 'ethereum-only'
    }
  }}
>
  {children}
</PrivyProvider>
What users see:
  1. MetaMask, Rainbow, and Coinbase Wallet prominently displayed
  2. WalletConnect option showing 100+ additional wallets
  3. Support for niche wallets not in the detected list
Best for:
  • Supporting wallets not yet in WalletConnect’s detection system
  • International users with regional wallets
  • Providing comprehensive coverage without cluttering the main list
This approach gives you the best of both worlds: prominent display of preferred wallets plus comprehensive fallback support through WalletConnect.

​
Platform Considerations

​
Mobile Browser Limitations

Wallets aren’t injected in mobile web browser environments, with the exception of the in-app browser for a few wallets (see In-App Browsers section below). Thus, adding detected_ethereum_wallets or detected_solana_wallets will show empty in mobile environments. On mobile:
  • ✅ Works: Specific wallet names (like 'metamask', 'phantom'), wallet_connect (shows full registry)
  • ❌ Doesn’t work: wallet_connect_qr, wallet_connect_qr_solana, detected_ethereum_wallets, detected_solana_wallets
Recommended mobile configuration: 
walletList: [
  'metamask', // Shows "Open in MetaMask" button
  'phantom',
  'rainbow'
];

​
In-App Browsers

On mobile, some wallets will connect via the in-app browser of that wallet’s mobile app. These wallets include:
  • Phantom (Ethereum and Solana)
  • Backpack (Ethereum and Solana)
  • OKX Wallet (Ethereum and Solana)
  • Solflare (Solana only)
  • Jupiter Wallet (Solana only)
When users access your app through one of these wallet’s built-in browsers:
  • The wallet is automatically detected and prioritized
  • No additional configuration needed
  • Appears first regardless of walletList order

​
Runtime Configuration

You can dynamically change the wallet list based on platform: 
const {connectWallet} = usePrivy();
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const openWalletModal = () => {
  connectWallet({
    walletList: isMobile
      ? ['metamask', 'phantom', 'rainbow', 'coinbase_wallet'] // Specific wallets for mobile
      : ['metamask', 'rainbow', 'coinbase_wallet', 'detected_ethereum_wallets', 'wallet_connect_qr'] // QR code for desktop
  });
};

​
Common Patterns Summary

PatternConfigurationUse Case
Simple Ethereum['metamask', 'coinbase_wallet', 'wallet_connect_qr']Standard Ethereum app (desktop)
Simple Solana['phantom', 'solflare', 'wallet_connect_qr_solana']Standard Solana app (desktop)
Maximum Compatibility['detected_ethereum_wallets', 'wallet_connect']Support all wallets
Mobile-First['metamask', 'phantom', 'rainbow', 'coinbase_wallet']Mobile-optimized
Minimal['phantom', 'metamask']Specific wallets only
Multi-ChainBoth Ethereum and Solana entries + both chain typesCross-chain apps

​
Need More Help?