Skip to content
Docs

Wallet Modal

Wallet Modal

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

  1. Quickly create a new smart wallet for new users
  2. Coinbase Wallet connection (supporting both smart wallets and EOA)
  3. MetaMask and Phantom connection

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
    • Terms and privacy policy links

The modal automatically handles:

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

::::