@wizardconnect/react

React components and hooks for integrating WizardConnect into dapps.

Installation

npm install @wizardconnect/react @wizardconnect/core @wizardconnect/dapp

React 18+ is required as a peer dependency.

Components

WizardConnectQRDialog

A portal-based modal dialog that displays a WizardConnect QR code for wallet pairing. Uses inline styles for framework independence (no Tailwind or CSS framework required).

import { WizardConnectQRDialog } from "@wizardconnect/react";

<WizardConnectQRDialog
  show={showDialog}
  onClose={() => setShowDialog(false)}
  uri={connection.uri}
  qrUri={connection.qrUri}
  logoUrl="/my-logo.png"
  theme={{
    dialogBackground: "#1e293b",
    headerBackground: "#1e293b",
  }}
/>;

Props:

| Prop | Type | Default | Description | | ----------- | ----------------------- | ------------------------------------ | --------------------------------------------------- | | show | boolean | required | Whether the dialog is visible | | onClose | () => void | required | Called when the user clicks close or the backdrop | | uri | string | required | Human-readable URI to display (wiz://...) | | qrUri | string | required | Alphanumeric-safe URI for QR encoding (WIZ://...) | | onCopy | (uri: string) => void | navigator.clipboard.writeText | Called when copy button is clicked | | theme | WizardConnectQRTheme | dark theme defaults | Color overrides | | title | string | "WizardConnect" | Dialog title | | subtitle | string | "Scan with your wallet to connect" | Subtitle text | | logoUrl | string | none | Logo for the header | | className | string | none | Additional CSS class on the outermost container |

AlphanumericQRCode

A standalone canvas-based QR code renderer. Uses Alphanumeric mode with error correction level H (30% recovery) to tolerate a center logo overlay.

import { AlphanumericQRCode } from "@wizardconnect/react";

<AlphanumericQRCode
  value="WIZ://..."
  size={280}
  foreground="#1e2a4a"
  background="#ffffff"
  logoUrl="/logo.png"
/>;

Hooks

useWizardConnect

Encapsulates the full WizardConnect relay lifecycle: relay initiation, DappConnectionManager management, key exchange events, session persistence, and auto-reconnect.

import { useWizardConnect, WizardConnectQRDialog } from "@wizardconnect/react";

function ConnectButton() {
  const {
    state, // "idle" | "connecting" | "connected" | "disconnected"
    manager, // DappConnectionManager (null until connect())
    uri, // connection URI (null until connect())
    qrUri, // QR-safe URI (null until connect())
    walletName, // wallet name (null until walletready)
    walletIcon, // wallet icon (null until walletready)
    connect, // () => boolean — initiate a new connection
    disconnect, // () => Promise<void> — disconnect and clean up
    error, // string | null — error message
  } = useWizardConnect({
    dappName: "My Dapp",
    dappIcon: "https://example.com/icon.png",
  });

  return (
    <>
      {state === "idle" && <button onClick={connect}>Connect</button>}
      {state === "connected" && <span>Connected to {walletName}</span>}

      {uri && qrUri && (
        <WizardConnectQRDialog
          show={state === "connecting"}
          onClose={disconnect}
          uri={uri}
          qrUri={qrUri}
        />
      )}
    </>
  );
}

Options:

| Option | Type | Default | Description | | ---------------- | ---------- | ------------------------- | ------------------------------------------ | | dappName | string | none | Display name sent in dapp_ready | | dappIcon | string | none | Icon URL sent in dapp_ready | | relayUrls | string[] | default relay | Explicit relay WebSocket URLs | | sessionKey | string | "wizardconnect-session" | localStorage key for session persistence | | persistSession | boolean | true | Whether to save session for auto-reconnect |

Using the manager:

After state becomes "connected", use manager to build your app-specific wallet adapter. The manager provides:

• getPubkey(childIndex, addressIndex) — derive pubkeys from xpubs
• sendSignRequest(request) — request transaction signatures
• sendSignCancel(sequence) — cancel an in-flight sign request
• on("walletready", callback) — listen for wallet handshake completion

See the @wizardconnect/dapp documentation for the full DappConnectionManager API.

Theme customization

All colors in WizardConnectQRDialog can be overridden via the theme prop:

const myTheme: WizardConnectQRTheme = {
  backdropColor: "rgba(0,0,0,0.5)",
  dialogBackground: "#1a1f2e",
  headerBackground: "#1a1f2e",
  titleColor: "#ffffff",
  subtitleColor: "#9ca3af",
  qrForeground: "#1e2a4a",
  qrBackground: "#ffffff",
  uriRowBackground: "rgba(31,41,55,0.6)",
  uriTextColor: "#9ca3af",
  borderColor: "#374151",
  closeButtonColor: "#9ca3af",
  copyButtonColor: "#9ca3af",
  logoUrl: "/my-qr-logo.png",
  qrSize: 280,
};

License

LGPL-3.0-or-later. See LICENSE.