Connect wallet widget

ConnectWalletOptionWidget is a prebuilt React component that lets a user connect an external wallet. It shows the wallets the user can connect, connects the one they choose through connectWalletOption, and returns the connected wallet account to your app. Use it when you want a working wallet connection screen without building the list, chain choice, QR code, and error screens yourself. To build your own screens instead, follow Connecting external wallets.

Prerequisites

@dynamic-labs-sdk/react-ui installed, its stylesheet imported, and your app wrapped in DynamicUiProvider, as described in React UI components.
A chain extension for each chain whose wallets you want to list, as described in Adding extensions. The widget lists only wallets on chains you registered.
To reach mobile wallets and wallets the user has not installed, the WalletConnect or MetaMask SDK extensions described in Reaching mobile and uninstalled wallets. Without them, the widget cannot show a pairing QR code.

Render the widget and handle onConnected:

import { ConnectWalletOptionWidget } from "@dynamic-labs-sdk/react-ui";

export const ConnectWallet = () => (
  <ConnectWalletOptionWidget
    onConnected={({ walletAccount }) => {
      console.log("Connected", walletAccount.address);
    }}
  />
);

The widget walks the user through these screens and moves between them on its own:

Wallet list. The user searches for and chooses a wallet.
Chain choice. The widget asks which chain to connect when the wallet supports more than one chain.
Approval. The widget waits while the user approves the connection in their wallet.
QR code. When the wallet connects by pairing, such as through WalletConnect, the widget shows a QR code for the user to scan.
In-app browser redirect. On mobile, a wallet that connects only inside its own in-app browser reopens your page there.
Connected, or an error. The widget confirms the connection, or explains that it failed and offers to try again.

Each screen has a Back control that returns to the previous screen and cancels any connection in progress.

Verify the wallet

onConnected receives an unverified wallet account. The wallet is connected, so you can read its address and ask it to sign, but the user has not yet proved they own it. When the wallet must be a trusted credential, such as to sign the user in or to link the wallet to their account, verify it with useVerifyWalletAccount, as described in Connect and verify a wallet:

import { ConnectWalletOptionWidget } from "@dynamic-labs-sdk/react-ui";
import { useVerifyWalletAccount } from "@dynamic-labs-sdk/react-hooks";

export const ConnectAndVerifyWallet = () => {
  const { mutateAsync: verifyWalletAccount } = useVerifyWalletAccount();

  return (
    <ConnectWalletOptionWidget
      onConnected={async ({ walletAccount }) => {
        // Asks the wallet to sign a message that proves ownership
        await verifyWalletAccount({ walletAccount });
      }}
    />
  );
};

Connecting external wallets lists the errors verification can throw, such as a wallet that is already linked to another user.

Reject a wallet and start over

onConnected also receives startOver, which sends the widget back to the wallet list so the user can choose another wallet. Call it when your app cannot use the wallet the user connected, such as one on a network you do not support. startOver does not disconnect the wallet. Show the user why you rejected it, and remove the account with useRemoveWalletAccount if you do not want it to stay connected.

import type { WalletAccount } from "@dynamic-labs-sdk/client";
import { useRemoveWalletAccount } from "@dynamic-labs-sdk/react-hooks";
import { ConnectWalletOptionWidget } from "@dynamic-labs-sdk/react-ui";

type ConnectSupportedWalletProps = {
  isSupported: (walletAccount: WalletAccount) => boolean;
};

export const ConnectSupportedWallet = ({ isSupported }: ConnectSupportedWalletProps) => {
  const { mutateAsync: removeWalletAccount } = useRemoveWalletAccount();

  return (
    <ConnectWalletOptionWidget
      onConnected={async ({ startOver, walletAccount }) => {
        if (!isSupported(walletAccount)) {
          await removeWalletAccount({ walletAccount });
          startOver();
        }
      }}
    />
  );
};

isSupported is your own check. startOver has no effect after the user has already left that connection.

Props

Prop	Type	Description
`onConnected`	`({ walletAccount, startOver }) => void`	Called when a wallet connects, with the unverified wallet account and a function that returns the widget to the wallet list
`onSelectWalletOption`	`(walletOption: WalletOption) => void`	Called when the user chooses a wallet from the list, before the widget connects it. Use it, for example, to clear a message about an earlier attempt
`onBack`	`() => void`	Shown as the Back control on the wallet list, the first screen. Use it to leave the widget, such as to close a dialog. Without it, the list has no Back
`children`	`ReactNode`	Content shown above every screen, such as a notice. It stays mounted while the user moves between screens
`className`	`string`	Extra class names for the widget’s root element

Change the text

Replace the widget’s titles and messages under the dyn-connect-wallet-option-widget slot of the DynamicUiProvider text dictionary, and the wallet list, chain choice, and QR code text under their own slots. Wallet connection text keys lists every key with its default and the placeholders it accepts, such as {wallet} for the wallet’s name.

Build your own layout from the views

The widget is built from views that the package also exports. Use them when you want the same wallet list inside a layout of your own, and connect the chosen wallet yourself with useConnectWalletOption:

WalletList shows the searchable list of wallets and calls onSelectWalletOption with the one the user chooses.
WalletChainList shows the chains a wallet supports, for the chain choice.
ProviderList shows a list of providers, such as wallets or exchanges, that you supply.

React UI components: install the package and change its text and styles.
Connecting external wallets: build the connection screens yourself.
Build a wallet picker: list every wallet a user can connect from the catalogue.
Flow payment widget: a payment widget that includes this wallet connection.

Learn

Implement

Connect wallet widget

Prerequisites

Add the widget

Verify the wallet

Reject a wallet and start over

Props

Change the text

Build your own layout from the views

​Prerequisites

​Add the widget

​Verify the wallet

​Reject a wallet and start over

​Props

​Change the text

​Build your own layout from the views

​Related

Prerequisites

Add the widget

Verify the wallet

Reject a wallet and start over

Props

Change the text

Build your own layout from the views

Related