WizardConnect/packages/react

@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.