Autoconnect & Session UX
Restore wallet sessions smoothly without surprising users.
Recipe
<WalletProvider wallets={wallets} autoConnect>When to reach for this:
- Return visitors on DeFi dashboards.
- Games and social apps with frequent txs.
- Reducing connect friction on mobile.
Working Example
"use client";
import { useWallet } from "@solana/wallet-adapter-react";
export function WalletGate({ children }: { children: React.ReactNode }) {
const { connected, connecting } = useWallet();
if (connecting) return <p>Restoring wallet session…</p>;
if (!connected) return <p>Connect wallet to view portfolio</p>;
return <>{children}</>;
}What this demonstrates:
- Show loading while autoConnect runs.
- Gate only features that need pubkey.
- Public reads stay available.
Deep Dive
How It Works
- Adapters persist last wallet choice in localStorage.
- autoConnect triggers on provider mount.
- Mobile may need manual reconnect after OS kills WebView.
- Pair with SIWS for server sessions separately.
Gotchas
- Instant modal on load - poor UX. Fix: silent autoConnect + inline status.
- Wrong wallet auto-reconnect - user owns multiple. Fix: easy wallet switcher.
- Stale sessions after network change - errors on send. Fix: cluster badge + reconnect CTA.
- autoConnect in SSR - crashes. Fix: client-only provider tree.
- No disconnect - users feel trapped. Fix: visible disconnect control.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Manual connect only | High-security admin apps | Consumer apps |
| Email + embedded wallet | Web2 onboarding | Sovereign wallet narrative |
FAQs
Devnet or mainnet?
Match RPC URL, wallet network, and program IDs to one cluster.
kit vs web3.js?
Use @solana/kit 7.0.0 for new frontend code.
Testing?
Surfpool 0.12.0 or devnet with faucet SOL.
Commitment level?
confirmed for UX; finalized for high-value reads.
Next.js App Router?
Providers in client layout; reads can be server-side.
Wallet rejected sign?
Show retry; never assume approval.
Priority fees?
Compute budget instructions on congested mainnet.
Mobile?
Use Mobile Wallet Adapter for React Native apps.
Security?
Never expose server keypairs to the browser.
IDL changes?
Regenerate typed clients in CI.
Related
- Connecting & Disconnecting - connect flow
- Wallet Adapter - autoConnect flag
- Transaction UX - loading states
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.