butr
Guides

Connect and disconnect

Discover wallets, connect by id, read status and errors, and disconnect.

Discover what's available

useDiscoveredWallets() is the live list of announced adapters. Filter out the ones already in the pool before rendering a picker:

import { useConnectWallet, useConnectedWallets, useDiscoveredWallets } from "@usebutr/react";

const connect = useConnectWallet();
const discovered = useDiscoveredWallets();
const connected = useConnectedWallets();

const available = discovered.filter((d) => !connected.some((c) => c.connector.id === d.id));

Connect

useConnectWallet() returns a function taking the adapter id and optional success/error callbacks:

{
  available.map((wallet) => (
    <button key={wallet.id} type="button" onClick={() => connect(wallet.id)}>
      Connect {wallet.name} ({wallet.chainPlatform})
    </button>
  ));
}

A single brand can expose more than one adapter (Phantom EVM + Phantom SVM). The reference apps group by name and render one button per chainPlatform.

Track status and errors

import { useConnectionStatus, useConnectionError } from "@usebutr/react";

const status = useConnectionStatus(); // "idle" | "connecting" | "success" | "error"
const error = useConnectionError(); // ConnectionError | null

{
  error ? (
    <p>
      {error.kind} — {error.message}
    </p>
  ) : null;
}

useIsConnecting() and useConnectingConnectorId() tell you which wallet is mid-flight, so you can spin only that button.

Disconnect

useDisconnectWallet() takes the connector id:

import { useDisconnectWallet } from "@usebutr/react";

const disconnect = useDisconnectWallet();
<button onClick={() => disconnect(wallet.connector.id)}>Disconnect</button>;

Disconnecting one wallet leaves the rest of the pool intact. It also sets the session-scoped isUserDisconnected flag (read via useIsUserDisconnected()), which suppresses auto-reconnect for the rest of the session — see Troubleshooting. To clear everything at once, use useResetWallet().

Source: apps/demo-vite/src/app.tsx and apps/demo-next/src/app/page.tsx in the butr repository. Run pnpm dev --filter=demo-vite (http://localhost:5173).

On this page