Wallet Connection

Patterns and best practices for implementing wallet connection flows in Stacks applications.

User Trust

Wallet connection is often the first interaction users have with your dApp. A clear, secure-feeling connection flow builds trust and confidence.

Connection Flow Overview

A typical wallet connection flow involves these steps:

1. User clicks "Connect Wallet" button
2. Modal displays available wallet options
3. User selects their preferred wallet
4. Wallet app prompts for connection approval
5. Connection confirmed, address displayed

Connect Button

The connect button should be prominently placed and clearly labeled. Use primary styling to indicate it's a key action.

<Button size="lg">Connect Wallet</Button>
<Button variant="outline">
  <WalletIcon className="mr-2 size-4" />
  Connect
</Button>

Wallet Selection Modal

Present users with clear wallet options. Show only wallets that are relevant to your platform (browser extension, mobile, hardware).

<Dialog>
  <DialogTrigger asChild>
    <Button>Connect Wallet</Button>
  </DialogTrigger>
  <DialogContent className="sm:max-w-md">
    <DialogHeader>
      <DialogTitle>Connect a Wallet</DialogTitle>
      <DialogDescription>
        Select your preferred wallet to connect to this app
      </DialogDescription>
    </DialogHeader>
    <div className="grid gap-2 py-4">
      {wallets.map((wallet) => (
        <button
          key={wallet.name}
          className="flex items-center gap-3 rounded-lg border border-border p-3 text-left transition-colors hover:bg-accent"
        >
          <img src={wallet.icon} alt={wallet.name} className="size-10 rounded-lg" />
          <div>
            <p className="font-medium">{wallet.name}</p>
            <p className="text-xs text-muted-foreground">{wallet.desc}</p>
          </div>
        </button>
      ))}
    </div>
  </DialogContent>
</Dialog>

Supported Wallets

Wallet	Type	Description
Leather	Browser extension & mobile	Full-featured Stacks wallet
Xverse	Mobile wallet	Mobile-first wallet experience
Ryder	Hardware wallet	Hardware security for Stacks

Connected State

Once connected, show the user's address (truncated) and provide easy access to disconnect or view account details.

<Button variant="outline" className="gap-2">
  <span className="size-2 rounded-full bg-green-500" />
  <span className="font-mono text-sm">SP2J6...9EJ7</span>
</Button>

Account Dropdown

Provide a dropdown menu for connected users to view details or disconnect:

<Card className="w-[280px]">
  <CardHeader className="pb-2">
    <div className="flex items-center justify-between">
      <CardTitle className="text-sm font-medium">Connected</CardTitle>
      <span className="size-2 rounded-full bg-green-500" />
    </div>
  </CardHeader>
  <CardContent className="space-y-3">
    <div className="flex items-center gap-3">
      <div className="flex size-10 items-center justify-center rounded-full bg-primary/10">
        <span className="text-sm font-medium text-primary">SP</span>
      </div>
      <div>
        <p className="font-mono text-sm">SP2J6...9EJ7</p>
        <p className="text-xs text-muted-foreground">Leather Wallet</p>
      </div>
    </div>
    <div className="flex gap-2">
      <Button variant="outline" size="sm" className="flex-1">Copy</Button>
      <Button variant="outline" size="sm" className="flex-1 text-destructive">Disconnect</Button>
    </div>
  </CardContent>
</Card>

Loading States

Show clear loading states during the connection process:

<div className="flex flex-col items-center gap-4 py-8">
  <div className="size-12 animate-pulse rounded-full bg-primary/20" />
  <div className="text-center">
    <p className="font-medium">Connecting to Leather...</p>
    <p className="text-sm text-muted-foreground">
      Confirm the connection in your wallet
    </p>
  </div>
  <Button variant="outline" size="sm">Cancel</Button>
</div>

Error Handling

Handle connection errors gracefully with clear messaging:

• Wallet not found: Guide users to install the wallet
• User rejected: Allow them to try again
• Network error: Suggest checking connection
• Wrong network: Prompt to switch networks

Best Practices

• Always show which wallet is connected
• Display the address prominently (truncated)
• Provide easy access to disconnect
• Remember connection state between sessions
• Handle the case when wallet extension is not installed
• Support deep links for mobile wallet connection
• Show clear loading and error states

Mobile Considerations

On mobile, wallet connection typically involves deep links to wallet apps:

• Detect mobile browsers and show mobile wallet options
• Use wallet-specific deep links
• Handle return from wallet app
• Consider WalletConnect for broader compatibility