WalletModal

WalletModal is a multi-state modal dialog that guides users through the wallet connection flow. It displays available wallets, handles the connection process, and shows success, error, or installation states.

💡 Tip

ConnectButton uses WalletModal internally. Use WalletModal directly only if you need a custom trigger button or want to control the modal state yourself.

Basic Usage

tsx

import { useState } from 'react';
import { WalletModal } from '@partylayer/react';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Connect Wallet
      </button>
      <WalletModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        onConnect={(sessionId) => {
          console.log('Connected!', sessionId);
          setIsOpen(false);
        }}
      />
    </>
  );
}

Props

Prop	Type	Default	Description
isOpen	boolean	—	Controls whether the modal is visible.
onClose	() => void	—	Called when the modal is dismissed (overlay click, close button, or Escape key).
onConnect	(sessionId: string) => void	—	Called when a wallet connection succeeds. Receives the new session ID.
walletIcons	Record<string, string>	—	Custom wallet icon URLs, keyed by walletId. Overrides registry and PartyLayerKit icons.

Modal Flow States

The modal transitions through several states during the connection process:

1. Wallet List

The default view showing all available wallets. Wallets are grouped into two categories:

CIP-0103 Native: wallets flagged cip0103.native in the registry (shown first with a "CIP-0103" badge)
Registry Wallets: verified wallets from the PartyLayer registry

Each wallet card shows the wallet name, icon, and a brief description. Verified wallets display a verification badge.

2. Connecting

After selecting a wallet, the modal shows a connecting state with the wallet's icon and a spinner animation. The wallet's native UI (extension popup, QR code, deep link) activates during this phase.

3. Success

On successful connection, a success animation plays and the onConnect callback fires with the session ID. The modal auto-closes after a brief delay.

4. Error

If connection fails, the modal shows the error message with a "Try Again" button. Common errors include user rejection, timeout, and transport failures.

5. Not Installed

If the selected wallet isn't detected, the modal shows an installation prompt with a link to the wallet's website (from the wallet's website field, with a built-in fallback URL for known wallets). Mobile flows may also show a deep-link button.

Registry Status

The modal displays a subtle registry status indicator showing whether wallet data is from a live registry fetch, cached, or if the registry is unreachable (with an offline badge).

Keyboard Navigation

Escape: closes the modal (explicit handler)
Wallet options are standard buttons, so Tab moves focus between them and Enter or Space activates the focused wallet (native browser behavior)

Custom Wallet Icons

You can override wallet icons at the modal level (in addition to PartyLayerKit):

tsx

<WalletModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  onConnect={handleConnect}
  walletIcons={{
    console: '/my-custom-console-icon.png',
    loop: '/my-custom-loop-icon.svg',
  }}
/>

ℹ️ Note

Icons passed to WalletModal merge with (and override) icons from PartyLayerKit's walletIcons prop.

PreviousConnectButton NextTheming