Skip to content

feat: useAppKitWallets hook#5297

Merged
enesozturk merged 37 commits intomainfrom
feat/wallets-hooks
Nov 10, 2025
Merged

feat: useAppKitWallets hook#5297
enesozturk merged 37 commits intomainfrom
feat/wallets-hooks

Conversation

@enesozturk
Copy link
Copy Markdown
Contributor

@enesozturk enesozturk commented Oct 30, 2025

Description

Implements new useAppKitWallets hook to let users build custom connect user interfaces.

Features

  • List, and connect with extension wallets.
  • List, search and connect the WalletConnect wallets.
  • Multi-chain.
  • Multi-platform.

Examples

Listing injected wallets:

const { data } = useAppKitWallets()

const injectedWallets = data.filter(wallet => wallet.isInjected)

injectedWallets.map(wallet =>{
    return <WalletItem name={wallet.name} imageSrc={wallet.imageUrl} />
})

Listing WalletConnect wallets:

const { data } = useAppKitWallets()

const wcWallets = data.filter(wallet => !wallet.isInjected)

wcWallets.map(wallet =>{
    return <WalletItem name={wallet.name} imageSrc={wallet.imageUrl} />
})

Connecting to a wallet:

const { connect } = useAppKitWallets()
...
await connect(wallet)

Changes

  • Implementation of useAppKitWallets hook and utils around it ConnectUtil
  • Implementing an example headless page to laboratory
  • Implementing E2E testing suite for headless example

Type of change

  • Chore (non-breaking change that addresses non-functional tasks, maintenance, or code quality improvements)
  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Associated Issues

For Linear issues: Closes APKT-4134, APKT-4133, APKT-4165, APKT-4135, APKT-4153, APKT-4180, APKT-4155
For GH issues: closes #...

Showcase (Optional)

If there is a UI change include the screenshots with before and after state.
If new feature is being introduced, include the link to demo recording.

Checklist

  • Code in this PR is covered by automated tests (Unit tests, E2E tests)
  • My changes generate no new warnings
  • I have reviewed my own code
  • I have filled out all required sections
  • I have tested my changes on the preview link
  • Approver of this PR confirms that the changes are tested on the preview link

Note

Add useAppKitWallets hook for listing/searching/connecting injected and WalletConnect wallets, plus a headless example and tests.

  • AppKit / Controllers
    • Add useAppKitWallets hook export in packages/appkit/exports/react.ts; wire through appkit-base-client and ConfigUtil.
    • Implement wallet discovery/connection flow in controllers (ConnectionController, ConnectorController, OptionsController) and utils (ConnectUtil, AssetUtil, TypeUtil, ConstantsUtil).
    • Expose related constants/exports in packages/appkit/exports/constants.ts and controllers exports.
  • UI/Scaffold
    • Update w3m-connector-list and wallet-button scaffold to support new hook-driven connection.
  • Laboratory (Headless demo)
    • Add headless connect UI components (InjectedWalletItem, WcWalletItem, QR, lists) and AppkitConnectDrawer.
    • Add multi-chain demo components and utility hooks like useDebounceValue.
  • Examples
    • New examples/next-appkit-headless Next.js app demonstrating headless usage (UI components, config, Tailwind setup).
  • Tests
    • Add E2E tests for headless flows and unit tests for config/controllers.
  • Misc
    • Update constants in common packages; adjust exports across wallet-button and controllers.

Written by Cursor Bugbot for commit 71ec508. This will update automatically on new commits. Configure here.

Copilot AI review requested due to automatic review settings October 30, 2025 14:38
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Oct 30, 2025

🦋 Changeset detected

Latest commit: 71ec508

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 25 packages
Name Type
@reown/appkit-wallet-button Patch
@reown/appkit-experimental Patch
@reown/appkit-controllers Patch
@reown/appkit-scaffold-ui Patch
@reown/appkit Patch
@reown/appkit-ui 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-wagmi Patch
@reown/appkit-core Patch
@reown/appkit-utils Patch
@reown/appkit-siwe Patch
@reown/appkit-siwx Patch
@reown/appkit-pay Patch
@reown/appkit-universal-connector Patch
@reown/appkit-cdn Patch
@reown/appkit-testing Patch
@reown/appkit-common Patch
@reown/appkit-polyfills Patch
@reown/appkit-wallet Patch
@reown/appkit-cli Patch
@reown/appkit-codemod Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel
Copy link
Copy Markdown

vercel bot commented Oct 30, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
appkit-basic-html Ready Ready Preview Comment Nov 10, 2025 4:04pm
appkit-demo Ready Ready Preview Comment Nov 10, 2025 4:04pm
appkit-gallery Ready Ready Preview Comment Nov 10, 2025 4:04pm
appkit-laboratory Ready Ready Preview Comment Nov 10, 2025 4:04pm
10 Skipped Deployments
Project Deployment Preview Comments Updated (UTC)
appkit-basic-example Ignored Ignored Nov 10, 2025 4:04pm
appkit-basic-sign-client-example Ignored Ignored Nov 10, 2025 4:04pm
appkit-basic-up-example Ignored Ignored Nov 10, 2025 4:04pm
appkit-ethers5-bera Ignored Ignored Nov 10, 2025 4:04pm
appkit-nansen-demo Ignored Ignored Nov 10, 2025 4:04pm
appkit-vue-solana Ignored Ignored Nov 10, 2025 4:04pm
appkit-wagmi-cdn-example Ignored Ignored Nov 10, 2025 4:04pm
ethereum-provider-wagmi-example Ignored Ignored Nov 10, 2025 4:04pm
next-wagmi-solana-bitcoin-example Ignored Ignored Nov 10, 2025 4:04pm
vue-wagmi-example Ignored Ignored Nov 10, 2025 4:04pm

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Oct 30, 2025

Visual Regression Test Results ✅ Passed

✨ No visual changes detected

Chromatic Build: https://www.chromatic.com/build?appId=6493191bf4b10fed8ca7353f&number=360
Storybook Preview: https://6493191bf4b10fed8ca7353f-evdfmojvnn.chromatic.com/

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR implements a new useAppKitWallets hook that enables developers to build custom wallet connection UIs. The implementation provides a headless approach to wallet connections, exposing the necessary data and functions while allowing full control over the UI.

Key changes:

  • New useAppKitWallets React hook for headless wallet management
  • Updated ConnectorController.getConnector to require namespace parameter
  • Added wcFetchingUri state to track WalletConnect URI loading
  • New utility ConnectUtil for unified wallet list management

Reviewed Changes

Copilot reviewed 35 out of 37 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
packages/controllers/exports/react.ts Adds useAppKitWallets hook with wallet list, connect, and fetch functions
packages/controllers/src/controllers/ConnectorController.ts Updates getConnector to require namespace, removes optional rdns parameter
packages/controllers/src/controllers/ConnectionController.ts Adds wcFetchingUri state for tracking URI loading
packages/controllers/src/utils/ConnectUtil.ts New utility for transforming connectors and wallets into unified list
packages/controllers/src/utils/TypeUtil.ts Moves ConnectorWithProviders interface and adds description field to WcWallet
packages/ui/src/components/wui-icon/index.ts Adds new chain icons (cosmos, polkadot, stellar)
apps/laboratory/* Test implementation and demo components for headless UI
pnpm-lock.yaml Updates zod dependency versions and adds qr-code libraries
Files not reviewed (1)
  • pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (1)

apps/laboratory/tests/headless.spec.ts:1

  • The condition check on line 21 is redundant since isPageLoaded is never modified to true in this flow. The code will always load the wallet page. Consider removing the condition or ensuring isPageLoaded is properly tracked.
import { WalletPage } from '@reown/appkit-testing'

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Oct 30, 2025

Warnings
⚠️

🔑 Potential UUID detected in packages/controllers/src/utils/AssetUtil.ts (line 18): ba0ba0cd-17c6-4806-a...

⚠️

🔑 Potential UUID detected in packages/controllers/src/utils/AssetUtil.ts (line 20): a1b58899-f671-4276-6...

⚠️

🔑 Potential UUID detected in packages/controllers/src/utils/AssetUtil.ts (line 24): 0b4838db-0161-4ffe-0...

⚠️

🔑 Potential UUID detected in packages/controllers/src/utils/AssetUtil.ts (line 32): 20f673c0-095e-49b2-0...

⚠️

🌐 Non-company domain introduced (host: dashboardreown.com) in examples/next-appkit-headless/app/page.tsx (line 41): https://dashboardreown.com

⚠️

🌐 Non-company domain introduced (host: avatars.githubusercontent.com) in examples/next-appkit-headless/lib/appkit.ts (line 65): https://avatars.githubusercontent.com/u/179229932?s=200&v=4

⚠️

🌐 Non-company domain introduced (host: www.w3.org) in examples/next-appkit-headless/components/InjectedWalletsContent.tsx (line 136): http://www.w3.org/2000/svg

⚠️

🌐 Non-company domain introduced (host: nextjs.org)) in examples/next-appkit-headless/README.md (line 1): https://nextjs.org)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 1): https://nextjs.org/docs/app/api-reference/cli/create-next-ap...

⚠️

🌐 Non-company domain introduced (host: localhost:3000](http:) in examples/next-appkit-headless/README.md (line 17): http://localhost:3000](http://localhost:3000)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 21): https://nextjs.org/docs/app/building-your-application/optimi...

⚠️

🌐 Non-company domain introduced (host: vercel.com) in examples/next-appkit-headless/README.md (line 21): https://vercel.com/font),

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 27): https://nextjs.org/docs)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 28): https://nextjs.org/learn)

⚠️

🌐 Non-company domain introduced (host: github.com) in examples/next-appkit-headless/README.md (line 30): https://github.com/vercel/next.js)

⚠️

🌐 Non-company domain introduced (host: vercel.com) in examples/next-appkit-headless/README.md (line 34): https://vercel.com/new?utm_medium=default-template&filter=ne...

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 36): https://nextjs.org/docs/app/building-your-application/deploy...

⚠️

🌐 Non-company domain introduced (host: dashboardreown.com) in examples/next-appkit-headless/app/page.tsx (line 41): https://dashboardreown.com

⚠️

🌐 Non-company domain introduced (host: avatars.githubusercontent.com) in examples/next-appkit-headless/lib/appkit.ts (line 65): https://avatars.githubusercontent.com/u/179229932?s=200&v=4

⚠️

🌐 Non-company domain introduced (host: www.w3.org) in examples/next-appkit-headless/components/InjectedWalletsContent.tsx (line 136): http://www.w3.org/2000/svg

⚠️

🌐 Non-company domain introduced (host: help.github.com) in examples/next-appkit-headless/.gitignore (line 1): https://help.github.com/articles/ignoring-files/

⚠️

🌐 Non-company domain introduced (host: ui.shadcn.com) in examples/next-appkit-headless/components.json (line 2): https://ui.shadcn.com/schema.json

⚠️

🌐 Non-company domain introduced (host: help.github.com) in examples/next-appkit-headless/.gitignore (line 1): https://help.github.com/articles/ignoring-files/

⚠️

🌐 Non-company domain introduced (host: ui.shadcn.com) in examples/next-appkit-headless/components.json (line 2): https://ui.shadcn.com/schema.json

⚠️

🌐 Non-company domain introduced (host: nextjs.org)) in examples/next-appkit-headless/README.md (line 1): https://nextjs.org)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 1): https://nextjs.org/docs/app/api-reference/cli/create-next-ap...

⚠️

🌐 Non-company domain introduced (host: localhost:3000](http:) in examples/next-appkit-headless/README.md (line 17): http://localhost:3000](http://localhost:3000)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 21): https://nextjs.org/docs/app/building-your-application/optimi...

⚠️

🌐 Non-company domain introduced (host: vercel.com) in examples/next-appkit-headless/README.md (line 21): https://vercel.com/font),

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 27): https://nextjs.org/docs)

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 28): https://nextjs.org/learn)

⚠️

🌐 Non-company domain introduced (host: github.com) in examples/next-appkit-headless/README.md (line 30): https://github.com/vercel/next.js)

⚠️

🌐 Non-company domain introduced (host: vercel.com) in examples/next-appkit-headless/README.md (line 34): https://vercel.com/new?utm_medium=default-template&filter=ne...

⚠️

🌐 Non-company domain introduced (host: nextjs.org) in examples/next-appkit-headless/README.md (line 36): https://nextjs.org/docs/app/building-your-application/deploy...

⚠️ Testing spec changed

Generated by 🚫 dangerJS against 71ec508

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Oct 30, 2025

📦 Bundle Size Check

All bundles are within size limits

📊 View detailed bundle sizes

> @reown/appkit-monorepo@1.7.1 size /home/runner/work/appkit/appkit


> size-limit

@reown/appkit - Main Entry
Size limit:   80 kB
Size:         73.89 kB with all dependencies, minified and gzipped
Loading time: 1.5 s    on slow 3G
Running time: 601 ms   on Snapdragon 410
Total time:   2.1 s
@reown/appkit/react
Size limit:   230 kB
Size:         227.32 kB with all dependencies, minified and gzipped
Loading time: 4.5 s     on slow 3G
Running time: 1.3 s     on Snapdragon 410
Total time:   5.7 s
@reown/appkit/vue
Size limit:   80 kB
Size:         73.89 kB with all dependencies, minified and gzipped
Loading time: 1.5 s    on slow 3G
Running time: 444 ms   on Snapdragon 410
Total time:   1.9 s
@reown/appkit-scaffold-ui
Size limit:   220 kB
Size:         208.03 kB with all dependencies, minified and gzipped
Loading time: 4.1 s     on slow 3G
Running time: 869 ms    on Snapdragon 410
Total time:   5 s
@reown/appkit-ui
Size limit:   500 kB
Size:         13.15 kB with all dependencies, minified and gzipped
Loading time: 257 ms   on slow 3G
Running time: 210 ms   on Snapdragon 410
Total time:   466 ms

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Oct 30, 2025

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 79.65% 38084 / 47809
🔵 Statements 79.65% 38084 / 47809
🔵 Functions 77.76% 4113 / 5289
🔵 Branches 86.47% 9237 / 10682
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
packages/appkit/exports/constants.ts 100% 100% 100% 100%
packages/appkit/exports/react.ts 50% 100% 33.33% 50% 50-62, 65-72
packages/appkit/src/client/appkit-base-client.ts 72.22% 85.71% 75.1% 72.22% 197, 210-213, 228-229, 235-236, 239, 295-296, 343, 381-382, 384-385, 390-391, 472-473, 509-515, 586-587, 609-624, 627, 661-662, 665, 706-710, 717-718, 721-722, 727-728, 739-762, 771-772, 789-809, 813-834, 837-843, 846-852, 855-861, 864-870, 873-883, 886-892, 895-902, 916-925, 928-934, 937-938, 941-942, 961-962, 985-1025, 1032-1044, 1050-1077, 1080-1090, 1122-1123, 1148-1149, 1154, 1169-1185, 1199, 1203-1211, 1242-1243, 1262-1265, 1269-1270, 1272-1273, 1308-1309, 1313-1334, 1339-1340, 1348-1349, 1352, 1446-1447, 1459-1460, 1488-1493, 1561-1562, 1574-1589, 1640-1641, 1653-1664, 1710-1723, 1768, 1774-1778, 1799-1814, 1817-1818, 1837-1840, 1876-1895, 1970-1971, 1977-2003, 2224-2225, 2262-2263, 2266-2267, 2283-2286, 2289-2290, 2310-2311, 2314-2315, 2327-2337, 2357-2358, 2361-2368, 2372-2373, 2395, 2400, 2405-2424, 2427-2436, 2443-2448, 2466-2467, 2470-2471, 2478-2479, 2518-2519, 2590-2591, 2594-2595, 2598-2601, 2604-2605, 2608-2609, 2612-2613, 2616-2617, 2620-2624, 2633-2642, 2651-2662, 216-342, 1019-1035, 1307-1594, 1777-1927, 2387
packages/appkit/src/utils/ConfigUtil.ts 95.31% 88.99% 70.21% 95.31% 42-43, 64-65, 91-92, 105, 116-117, 130, 160, 212, 261-262
packages/common/src/utils/ConstantsUtil.ts 100% 0% 100% 100%
packages/controllers/exports/index.ts 100% 100% 100% 100%
packages/controllers/exports/react.ts 62.96% 92.1% 38.88% 62.96% 59-68, 89-97, 104-111, 126, 134, 152, 350-429
packages/controllers/src/controllers/ConnectionController.ts 84.75% 87.6% 53.84% 84.75% 173, 232-236, 239-243, 285-289, 297-298, 305-324, 339, 343, 347, 351, 355, 359, 363, 367, 371, 452, 456, 478-482, 497-499, 510-511, 546-547, 557-558, 560-561, 569-570, 572-573, 592-593
packages/controllers/src/controllers/ConnectorController.ts 86.53% 96.15% 74.6% 86.53% 63-65, 83-84, 130-132, 143, 198-199, 225-233, 296-316, 333-338, 415, 419
packages/controllers/src/controllers/OptionsController.ts 88% 98.41% 55.42% 88% 246, 275-276, 328, 332, 390-393, 397-400, 404-407, 411-414, 469, 369, 464
packages/controllers/src/utils/AssetUtil.ts 75% 94.73% 65.21% 75% 44-45, 59, 64, 108-109, 120-121, 135-139, 148-159, 168-179, 188-189
packages/controllers/src/utils/ConnectUtil.ts 6.66% 100% 0% 6.66% 41-116, 63-111
packages/controllers/src/utils/ConstantsUtil.ts 100% 0% 100% 100%
packages/scaffold-ui/src/partials/w3m-connector-list/index.ts 69.63% 83.6% 63.63% 69.63% 73, 76-78, 83-87, 91-92, 98, 234, 275, 279-333, 364, 368-410
packages/wallet-button/src/client.ts 60.71% 76.47% 36.36% 60.71% 42-43, 52-53, 56-65, 72-73, 75-76, 84, 94-103, 105-106, 111-112
packages/wallet-button/src/scaffold-ui/appkit-wallet-button/index.ts 79.06% 92.18% 69.23% 79.06% 53, 61-62, 75-76, 83-84, 100-101, 204-205, 207-208, 221-245
Generated in workflow #16278 for commit 71ec508 by the Vitest Coverage Report Action

@linear
Copy link
Copy Markdown

linear bot commented Nov 5, 2025

@socket-security
Copy link
Copy Markdown

socket-security bot commented Nov 10, 2025

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report

@linear
Copy link
Copy Markdown

linear bot commented Nov 10, 2025

Copy link
Copy Markdown
Contributor

@svenvoskamp svenvoskamp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants