reown-com · 0xmkh · Jun 26, 2026 · Jun 26, 2026 · Jun 26, 2026 · Jun 26, 2026
diff --git a/.changeset/headless-wallets-on-client.md b/.changeset/headless-wallets-on-client.md
@@ -0,0 +1,32 @@
+---
+'@reown/appkit-utils': patch
+'@reown/appkit': patch
+'@reown/appkit-cdn': patch
+'@reown/appkit-cli': patch
+'@reown/appkit-codemod': patch
+'@reown/appkit-common': patch
+'@reown/appkit-core': patch
+'@reown/appkit-experimental': patch
+'@reown/appkit-pay': patch
+'@reown/appkit-polyfills': patch
+'@reown/appkit-scaffold-ui': patch
+'@reown/appkit-siwe': patch
+'@reown/appkit-siwx': patch
+'@reown/appkit-testing': patch
+'@reown/appkit-ui': patch
+'@reown/appkit-universal-connector': patch
+'@reown/appkit-wallet-button': patch
+'@reown/appkit-wallet': patch
+'@reown/appkit-controllers': patch
+'@reown/appkit-adapter-bitcoin': patch
+'@reown/appkit-adapter-ethers': patch
+'@reown/appkit-adapter-ethers5': patch
+'@reown/appkit-adapter-solana': patch
+'@reown/appkit-adapter-ton': patch
+'@reown/appkit-adapter-tron': patch
+'@reown/appkit-adapter-wagmi': patch
+---
+
+Expose the headless wallet list imperatively on the AppKit client, so a non-React host can list / search / connect wallets without the `useAppKitWallets` React hook.
+
+New `AppKit` instance methods: `fetchWallets(options?)`, `getWalletList()`, `subscribeWalletList(cb)`, `getWalletConnectUri(options?)`, and `connectWallet(wallet, namespace?, options?)`. The shared imperative logic lives in a new `HeadlessWalletUtil` (`@reown/appkit-controllers`), which both the client methods and the React hook can use — one tested code path for headless wallet listing, search, pagination, the WalletConnect URI, and programmatic connect (injected / API / mobile-deeplink).
diff --git a/examples/html-headless/index.html b/examples/html-headless/index.html
@@ -0,0 +1,46 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AppKit Headless (vanilla) Example</title>
+    <link rel="stylesheet" href="/src/main.css" />
+  </head>
+  <body>
+    <main class="page">
+      <h1 class="title">AppKit Headless — vanilla JS</h1>
+      <p class="subtitle">
+        A custom wallet modal driven entirely by the imperative AppKit client API (<code
+          >appKit.fetchWallets</code
+        >
+        / <code>getWalletList</code> / <code>subscribeWalletList</code> /
+        <code>connectWallet</code>) — no React, no AppKit modal.
+      </p>
+
+      <!-- Connected account -->
+      <section id="account" class="account" hidden>
+        <span id="account-address" class="account__address"></span>
+        <button id="disconnect" class="btn btn--outline">Disconnect</button>
+      </section>
+
+      <!-- Open the custom wallet modal -->
+      <button id="open" class="btn">Connect wallet</button>
+
+      <!-- Custom headless wallet modal -->
+      <div id="modal" class="modal" hidden>
+        <div class="modal__backdrop" data-close></div>
+        <div class="modal__card">
+          <div class="modal__header">
+            <h2>Select a wallet</h2>
+            <button class="modal__close" data-close>&times;</button>
+          </div>
+          <!-- Wallet list with infinite loading -->
+          <div id="wallet-list" class="wallet-list"></div>
+          <p id="list-status" class="wallet-list__status"></p>
+        </div>
+      </div>
+    </main>
+
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>
diff --git a/examples/html-headless/package.json b/examples/html-headless/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@examples/html-headless",
+  "private": true,
+  "version": "1.2.0",
+  "scripts": {
+    "dev": "vite --port 3013",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@reown/appkit-adapter-wagmi": "workspace:*",
+    "@reown/appkit": "workspace:*"
+  },
+  "devDependencies": {
+    "vite": "5.4.20"
+  }
+}
diff --git a/examples/html-headless/src/main.css b/examples/html-headless/src/main.css
@@ -0,0 +1,172 @@
+:root {
+  --bg: #0b0d12;
+  --panel: #151821;
+  --border: #262b38;
+  --text: #e7e9ee;
+  --muted: #9aa3b2;
+  --accent: #3396ff;
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+  display: flex;
+  justify-content: center;
+  padding: 3rem 1rem;
+}
+
+.page {
+  width: 100%;
+  max-width: 30rem;
+}
+
+.title {
+  margin: 0;
+  font-size: 1.5rem;
+}
+
+.subtitle {
+  color: var(--muted);
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+.subtitle code {
+  color: var(--accent);
+  font-size: 0.82rem;
+}
+
+.btn {
+  padding: 0.7rem 1.1rem;
+  border: 0;
+  border-radius: 10px;
+  background: var(--accent);
+  color: #fff;
+  font-size: 0.95rem;
+  cursor: pointer;
+}
+
+.btn--outline {
+  background: transparent;
+  border: 1px solid var(--border);
+  color: var(--text);
+  padding: 0.4rem 0.75rem;
+  font-size: 0.85rem;
+}
+
+.account {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.85rem 1rem;
+  margin-bottom: 1rem;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+}
+
+.account__address {
+  font-family: ui-monospace, monospace;
+}
+
+/* -- Modal ----------------------------------------------------------------- */
+.modal {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+}
+
+.modal__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+}
+
+.modal__card {
+  position: relative;
+  width: 100%;
+  max-width: 24rem;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  padding: 1.25rem;
+}
+
+.modal__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 0.75rem;
+}
+
+.modal__header h2 {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.modal__close {
+  background: none;
+  border: 0;
+  color: var(--muted);
+  font-size: 1.4rem;
+  cursor: pointer;
+  line-height: 1;
+}
+
+.wallet-list {
+  max-height: 22rem;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.wallet {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  width: 100%;
+  padding: 0.6rem 0.7rem;
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  color: var(--text);
+  cursor: pointer;
+  font-size: 0.95rem;
+  text-align: left;
+}
+
+.wallet:hover {
+  border-color: var(--accent);
+}
+
+.wallet__icon {
+  width: 2rem;
+  height: 2rem;
+  border-radius: 8px;
+  object-fit: cover;
+  background: var(--bg);
+  flex-shrink: 0;
+}
+
+.wallet-list__status {
+  margin: 0.75rem 0 0;
+  text-align: center;
+  font-size: 0.8rem;
+  color: var(--muted);
+}