feat: account linking wallet picker UI & improved linking/error feedback

[lionellbriones]

Jira Link

Description

This PR adds a dedicated wallet picker flow for account linking in the modal SDK, along with improved success/error feedback UI for all account linking and switching operations.

New: Parameterless linkAccount() with built-in wallet picker

• linkAccount(params?) — connectorName is now optional in @web3auth/modal. When omitted, the modal opens a dedicated wallet picker (reusing the ConnectWallet screen) so the user can select which wallet to link without the app needing to know which wallets are available.
• A new pickerActive state flag in AccountLinkingState routes wallet selection from the ConnectWallet UI into the linking flow instead of the regular login flow.
• New LoginModal methods: startAccountLinkingPicker, endAccountLinkingPicker.

Improved success & error feedback

• New LoginModal methods: startConnectingLoader, markLoaderAuthorizing, endConnectingLoader — provide a unified way to show connecting → success/error states after account linking and switching.
• formatAccountLinkingErrorMessage maps AccountLinkingError codes to human-readable messages (distinguishing link vs. unlink failures).
• The Loader component now receives an optional message prop to display dynamic post-loading messages (success or error) pulled from i18n or passed as raw strings.
• ConnectedStatus and ErroredStatus in the Loader now guard against empty messages so no empty <p> is rendered.

ConnectWallet UI enhancements

• ConnectWalletHeader accepts a new isLinking prop: hides the back button and shows "Link Your Wallet" instead of "Connect Your Wallet" when in picker mode.
• New i18n key modal.linkYourWallet added across all 11 locale files.
• The Root layout no longer conditionally stretches the content container based on loader visibility (minor layout fix that prevents height jumps).

How has this been tested?

Screenshots (if appropriate)

Linking with connectorName

linking-metamask-success.mov

Linking with wallet picker

linking-wallet-picker.mov

Linking Error

linking-wallet-connect-failed.mov

Types of changes

• 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)

Checklist

• My code follows the code style of this project. (run lint)
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

---

Note

Medium Risk
Modifies modal account-linking/switching control flow and loader state handling, which can affect connection UX and cleanup behavior (especially around WalletConnect). API surface changes (linkAccount params optional) may impact downstream type expectations in modal integrations.

Overview
Adds a dedicated wallet-picker flow for account linking in @web3auth/modal: linkAccount() now accepts optional params and, when connectorName is omitted, opens the modal’s wallet list in a new pickerActive mode that routes the user’s selection into the linking flow.

Refactors account link/switch UX to use new LoginModal loader helpers (startConnectingLoader, markLoaderAuthorizing, endConnectingLoader), improves cleanup/cancel behavior, and standardizes error messaging (including link vs unlink formatting). UI updates adjust ConnectWallet header/back behavior during linking, pass translated post-loading messages into Loader, and add new i18n strings across locales; demo Vue app adds a “link with picker” button.

Also updates no-modal wrappers/types so linkAccount takes optional params in shared interfaces/hooks, while @web3auth/no-modal enforces connectorName at runtime.

^{Reviewed by Cursor Bugbot for commit 33632c2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
web3auth-web	Ready	Preview, Comment	May 20, 2026 8:22am

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8b6e46d. Configure here.}