Skip to content
Get help

Wallet Modal

Wallet Modal

WalletModal offers users multiple wallet connection options. The modal automatically appears when users click the ConnectWallet component and provides several connection paths:

  1. Quickly create a new smart wallet for new users
  2. Coinbase Wallet connection (supporting both smart wallets and EOA)
  3. MetaMask connection
  4. Phantom connection
  5. Rabby, Frame, and Trust Wallet connections (optional)

Walkthrough

Configure the OnchainKitProvider with modal settings:

providers.tsx
<OnchainKitProvider
  apiKey={process.env.ONCHAINKIT_API_KEY}
  chain={base}
  config={{
    appearance: {
      name: 'Your App Name',        // Displayed in modal header
      logo: 'https://your-logo.com',// Displayed in modal header
      mode: 'auto',                 // 'light' | 'dark' | 'auto'
      theme: 'default',             // 'default' or custom theme
    },
    wallet: { 
      display: 'modal', 
      termsUrl: 'https://...', 
      privacyUrl: 'https://...', 
      },
  }}
>
  {children}
</OnchainKitProvider>

Use the ConnectWallet component in your UI:

App.tsx
<Wallet>
  <ConnectWallet>
    <Avatar className="h-6 w-6" />
    <Name />
  </ConnectWallet>
  <WalletDropdown>
    <Identity className="px-4 pt-3 pb-2" hasCopyAddressOnClick>
      <Avatar />
      <Name />
      <Address />
      <EthBalance />
    </Identity>
    <WalletDropdownDisconnect />
  </WalletDropdown>
</Wallet>

Components

The Wallet Modal components are designed to work together hierarchically:

  • <OnchainKitProvider /> - Configures the modal settings and appearance
  • <ConnectWallet /> - Triggers the modal to open when clicked
  • <WalletModal /> - The modal interface itself, containing:
    • Smart wallet creation flow
    • Coinbase Wallet connection
    • MetaMask connection
    • Phantom connection
    • Rabby, Trust, and Frame Wallet connections (if enabled)
    • Terms and privacy policy links

The modal automatically handles:

  • Wallet connection states
  • Error handling
  • Mobile/desktop responsive behavior
  • Theme customization
  • Terms/privacy policy display

Additional Wallet Support

By default, the wallet modal includes Coinbase Wallet, MetaMask, and Phantom as connection options. You can enable additional wallet support by configuring the supportedWallets object in the OnchainKitProvider:

<OnchainKitProvider
  apiKey={process.env.ONCHAINKIT_API_KEY}
  chain={base}
  config={{
    appearance: {
      name: 'Your App Name',
      logo: 'https://your-logo.com',
      mode: 'auto',
      theme: 'default',
    },
    wallet: {
      display: 'modal',
      termsUrl: 'https://...',
      privacyUrl: 'https://...',
      supportedWallets: { 
        rabby: true, 
        trust: true, 
        frame: true, 
      }, 
    },
  }}
>
  {children}
</OnchainKitProvider>

Each wallet can be individually enabled or disabled as needed. If no supportedWallets configuration is provided, the additional wallets will be disabled by default. ::::