# @wizardconnect/react

> React components and hooks for WizardConnect dapp integration

Latest version **0.2.3** (published 2026-09-24) · 0 weekly downloads

## Install

```sh
npm install @wizardconnect/react
pnpm add @wizardconnect/react
yarn add @wizardconnect/react
bun add @wizardconnect/react
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2026-09-24 |
| First published | 2026-03-18 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 53.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (Unknown) |
| Maintainers | dagurval |

## Links

- npm: https://www.npmjs.com/package/@wizardconnect/react
- Repository: https://gitlab.com/riftenlabs/lib/wizardconnect
- Homepage: https://gitlab.com/riftenlabs/lib/wizardconnect#readme
- Issues: https://gitlab.com/riftenlabs/lib/wizardconnect/issues
- npm.io page: https://npm.io/package/@wizardconnect/react

## Dependencies (3)

- [qrcode-generator](https://npm.io/package/qrcode-generator.md) ^1.4.4
- [@wizardconnect/core](https://npm.io/package/@wizardconnect/core.md) *
- [@wizardconnect/dapp](https://npm.io/package/@wizardconnect/dapp.md) *

## Recent versions

- 0.2.3 (latest) — 2026-09-24
- 0.2.2 — 2026-05-09
- 0.2.1 — 2026-04-29
- 0.1.7 — 2026-04-16
- 0.1.6 — 2026-04-14
- 0.1.5 — 2026-04-03
- 0.1.4 — 2026-03-26
- 0.1.3 — 2026-03-23
- 0.1.2 — 2026-03-23
- 0.1.1 — 2026-03-18
- 0.1.0 — 2026-03-18

## README

# @wizardconnect/react

React components and hooks for integrating WizardConnect into dapps.

## Installation

```bash
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).

```tsx
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.

```tsx
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.

```tsx
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](../../docs/dapp.md) for the full `DappConnectionManager` API.

## Theme customization

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

```tsx
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](../../LICENSE).

---
_Source: https://npm.io/package/@wizardconnect/react · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._