React Hooks

PartyLayer provides 11 React hooks for accessing wallet state, performing operations, and managing sessions. All hooks must be used within a PartyLayerKit or PartyLayerProvider.

Core Hooks

usePartyLayer

Access the underlying PartyLayerClient instance directly.

tsx

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

function Advanced() {
  const client = usePartyLayer();

  // Access any client method
  const wallets = await client.listWallets();
  const provider = client.asProvider();
}

ℹ️ Note

Use this hook when you need direct access to the SDK client for operations not covered by the other hooks (e.g., asProvider(), registerAdapter()).

useSession

Get the active wallet session. Returns null when disconnected. Automatically updates when the session changes.

tsx

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

function Profile() {
  const session = useSession();

  if (!session) return <p>Not connected</p>;

  return (
    <div>
      <p>Party ID: {session.partyId}</p>
      <p>Wallet: {session.walletId}</p>
      <p>Network: {session.network}</p>
      <p>Capabilities: {session.capabilitiesSnapshot.join(', ')}</p>
    </div>
  );
}

Return type: Session | null

The Session object includes: sessionId, walletId, partyId, network, createdAt, expiresAt, origin, capabilitiesSnapshot, metadata.

useWallets

Fetch and list all available wallets (from both the registry and registered adapters).

tsx

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

function WalletList() {
  const { wallets, isLoading, error } = useWallets();

  if (isLoading) return <p>Loading wallets...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {wallets.map(w => (
        <li key={w.walletId}>
          {w.name} — {w.capabilities.join(', ')}
        </li>
      ))}
    </ul>
  );
}

Return type: { wallets: WalletInfo[], isLoading: boolean, error: Error | null }

Connection Hooks

useConnect

Connect to a wallet programmatically.

tsx

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

function CustomConnect() {
  const { connect, isConnecting, error, reset } = useConnect();

  const handleConnect = async () => {
    const session = await connect({ walletId: 'console' });
    if (session) {
      console.log('Connected:', session.partyId);
    }
  };

  return (
    <div>
      <button onClick={handleConnect} disabled={isConnecting}>
        {isConnecting ? 'Connecting...' : 'Connect Console'}
      </button>
      {error && (
        <div>
          <p>Error: {error.message}</p>
          <button onClick={reset}>Reset</button>
        </div>
      )}
    </div>
  );
}

Return type: { connect: (options?) => Promise<Session | null>, isConnecting: boolean, error: Error | null, reset: () => void }

The options parameter accepts: walletId (optional — if omitted, opens the modal).

useDisconnect

Disconnect the active wallet session.

tsx

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

function DisconnectButton() {
  const { disconnect, isDisconnecting, error } = useDisconnect();

  return (
    <button onClick={() => disconnect()} disabled={isDisconnecting}>
      {isDisconnecting ? 'Disconnecting...' : 'Disconnect'}
    </button>
  );
}

Return type: { disconnect: () => Promise<void>, isDisconnecting: boolean, error: Error | null }

Signing Hooks

useSignMessage

Sign an arbitrary message with the connected wallet.

tsx

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

function SignDemo() {
  const { signMessage, isSigning, error } = useSignMessage();

  const handleSign = async () => {
    const result = await signMessage({
      message: 'Hello from PartyLayer!',
      nonce: crypto.randomUUID(),
    });

    if (result) {
      console.log('Signature:', result.signature);
      console.log('Signed by:', result.partyId);
    }
  };

  return (
    <button onClick={handleSign} disabled={isSigning}>
      {isSigning ? 'Signing...' : 'Sign Message'}
    </button>
  );
}

Return type: { signMessage: (params) => Promise<SignedMessage | null>, isSigning: boolean, error: Error | null }

SignedMessage includes: signature, partyId, message, nonce, domain.

useSignTransaction

Sign a transaction without submitting it.

tsx

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

function SignTx() {
  const { signTransaction, isSigning, error } = useSignTransaction();

  const handleSign = async () => {
    const result = await signTransaction({
      tx: { templateId: '...', choiceId: '...', argument: { /* ... */ } },
    });

    if (result) {
      console.log('Transaction hash:', result.transactionHash);
      console.log('Signed payload:', result.signedTx);
    }
  };

  return <button onClick={handleSign}>{isSigning ? 'Signing...' : 'Sign Transaction'}</button>;
}

Return type: { signTransaction: (params) => Promise<SignedTransaction | null>, isSigning: boolean, error: Error | null }

useSubmitTransaction

Sign and submit a transaction to the ledger in one step.

tsx

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

function SubmitTx() {
  const { submitTransaction, isSubmitting, error } = useSubmitTransaction();

  const handleSubmit = async () => {
    const receipt = await submitTransaction({
      signedTx: signedPayload,  // Pass the signed transaction
    });

    if (receipt) {
      console.log('TX Hash:', receipt.transactionHash);
      console.log('Submitted at:', new Date(receipt.submittedAt));
      console.log('Command ID:', receipt.commandId);
    }
  };

  return <button onClick={handleSubmit}>{isSubmitting ? 'Submitting...' : 'Submit'}</button>;
}

Return type: { submitTransaction: (params) => Promise<TxReceipt | null>, isSubmitting: boolean, error: Error | null }

Utility Hooks

useRegistryStatus

Get the current wallet registry status and refresh it.

tsx

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

function RegistryInfo() {
  const { status, refresh } = useRegistryStatus();

  if (!status) return <p>No registry data</p>;

  return (
    <div>
      <p>Source: {status.source}</p>
      <p>Verified: {status.verified ? 'Yes' : 'No'}</p>
      <p>Channel: {status.channel}</p>
      <p>Stale: {status.stale ? 'Yes' : 'No'}</p>
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}

Return type: { status: RegistryStatus | null, refresh: () => Promise<void> }

useWalletIcons

Access the wallet icon overrides provided by PartyLayerKit.

tsx

import { useWalletIcons, resolveWalletIcon } from '@partylayer/react';

function WalletIcon({ walletId, registryIcon }: { walletId: string; registryIcon?: string }) {
  const walletIcons = useWalletIcons();
  const iconUrl = resolveWalletIcon(walletId, walletIcons, registryIcon);

  if (!iconUrl) return <div className="fallback-icon" />;
  return <img src={iconUrl} alt={walletId} width={32} height={32} />;
}

Return type: Record<string, string>

useTheme

Access the current PartyLayer theme.

tsx

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

function ThemedComponent() {
  const theme = useTheme();

  return (
    <div style={{
      background: theme.colors.background,
      color: theme.colors.text,
      fontFamily: theme.fontFamily,
    }}>
      Current mode: {theme.mode}
    </div>
  );
}

Return type: PartyLayerTheme — see Theming for the full interface.

PreviousTheming NextVanilla JS