ConnectButton

ConnectButton is a ready-to-use component that handles the entire wallet connection lifecycle. It renders a connect button when disconnected and shows the connected party ID with a disconnect dropdown when connected.

Basic Usage

tsx

import { ConnectButton } from '@partylayer/react';

function Navbar() {
  return (
    <nav>
      <h1>My dApp</h1>
      <ConnectButton />
    </nav>
  );
}

Props

Prop	Type	Default	Description
label	string	"Connect Wallet"	Text shown on the button when disconnected.
accountStatus	"avatar" \| "address" \| "full"	"full"	Choose avatar-only, address-only or full account button display.
connectedLabel	"address" \| "wallet" \| "custom"	"address"	What to display when connected: truncated party ID, wallet ID, or custom format.
formatAddress	(partyId: string) => string	—	Custom formatter for the connected label. Only used when connectedLabel="custom".
className	string	—	CSS class name for the outer container.
style	CSSProperties	—	Inline styles for the outer container.
showDisconnect	boolean	true	Show the account dropdown and disconnect action. False renders a compact account display without the menu.
holdings	AccountHoldings	—	Authorized holdings bound to the exact party and CAIP-2 network; shows available and locked balances in the account panel.

Button States

With optional backend authentication, the same button also offers explicit sign-in and app sign-out. Transactions recorded through useTransactionFlow appear in the account panel automatically. The panel shows the actual connected network, wallet-side change guidance and any supplied authorized holdings. See Authentication,Transaction lifecycle and Wallet balances.

ConnectButton automatically transitions between three states:

Disconnected

Shows a yellow branded button with the connect label. Clicking opens the WalletModal.

tsx

<ConnectButton label="Connect Wallet" />

Connecting

While a wallet connection is in progress, the button shows a loading spinner. This state is automatic, no configuration needed.

Connected

Shows the connected party ID (truncated) with a green status dot. Clicking opens a dropdown with session details and a disconnect button.

The dropdown shows:

Status badge: green "CONNECTED" indicator
Party ID: the full connected party ID
Wallet ID: which wallet is connected
Disconnect button: cleanly ends the session

Keyboard Navigation

Opening the wallet dialog moves focus inside. Tab and Shift+Tab stay within the dialog; Escape closes it and returns focus to the opener. Wallet-owned approval windows keep their own keyboard handling.

The connected account menu supports Enter/Space, Arrow Up/Down, Home/End, Escape to close and return to the account button, and Tab to leave the menu. Avatar-only buttons include an accessible account name. The component's buttons do not submit an enclosing application form.

Connected Label Formats

tsx

// Show truncated party ID (default)
<ConnectButton connectedLabel="address" />
// Result: "party::abc1...xyz9"

// Show the wallet ID
<ConnectButton connectedLabel="wallet" />
// Result: "console"

// Custom format
<ConnectButton
  connectedLabel="custom"
  formatAddress={(partyId) => `Connected: ${partyId.slice(0, 12)}...`}
/>
// Result: "Connected: party::abc1..."

Custom Styling

You can override styles with the style and className props:

tsx

<ConnectButton
  style={{ borderRadius: 8, fontSize: 16 }}
  className="my-connect-button"
/>

💡 Custom Button

If you need full control over the button rendering, use the WalletModal component directly with your own trigger button, plus the useAccount and useDisconnect hooks. See WalletModal for details.

Building a Custom Connect Button

For full control, skip ConnectButton and use hooks directly:

tsx

import { useState } from 'react';
import { WalletModal, useAccount, useDisconnect, truncatePartyId } from '@partylayer/react';

function CustomConnect() {
  const [modalOpen, setModalOpen] = useState(false);
  const { isConnected, party } = useAccount();
  const { disconnect } = useDisconnect();

  if (isConnected) {
    return (
      <div>
        <span>{truncatePartyId(String(party))}</span>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  return (
    <>
      <button onClick={() => setModalOpen(true)}>Connect</button>
      <WalletModal
        isOpen={modalOpen}
        onClose={() => setModalOpen(false)}
        onConnect={() => setModalOpen(false)}
      />
    </>
  );
}

PreviousPartyLayerKit NextWalletModal