> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect wallet widget

> Add ConnectWalletOptionWidget from @dynamic-labs-sdk/react-ui to let users choose an external wallet and connect it, then verify the wallet when you need proof of ownership.

`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`](https://www.dynamic.xyz/docs/javascript/reference/wallets/connect-wallet-option), 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](https://www.dynamic.xyz/docs/javascript/building-ui/connecting-external-wallets.md).

## Prerequisites

* `@dynamic-labs-sdk/react-ui` installed, its stylesheet imported, and your app wrapped in `DynamicUiProvider`, as described in [React UI components](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/overview.md).
* A chain extension for each chain whose wallets you want to list, as described in [Adding extensions](https://www.dynamic.xyz/docs/javascript/reference/adding-extensions.md). 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](https://www.dynamic.xyz/docs/javascript/building-ui/connecting-external-wallets.md#reaching-mobile-and-uninstalled-wallets). Without them, the widget cannot show a pairing QR code.

## Add the widget

Render the widget and handle `onConnected`:

```tsx theme={"system"}
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:

1. **Wallet list.** The user searches for and chooses a wallet.
2. **Chain choice.** The widget asks which chain to connect when the wallet supports more than one chain.
3. **Approval.** The widget waits while the user approves the connection in their wallet.
4. **QR code.** When the wallet connects by pairing, such as through WalletConnect, the widget shows a QR code for the user to scan.
5. **In-app browser redirect.** On mobile, a wallet that connects only inside its own in-app browser reopens your page there.
6. **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](https://www.dynamic.xyz/docs/javascript/reference/wallets/connect-and-verify-wallet.md):

```tsx theme={"system"}
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](https://www.dynamic.xyz/docs/javascript/building-ui/connecting-external-wallets.md#handling-errors) 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`](https://www.dynamic.xyz/docs/javascript/reference/wallets/remove-wallet-account) if you do not want it to stay connected.

```tsx theme={"system"}
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](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/text-reference.md#wallet-connection) 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`](https://www.dynamic.xyz/docs/javascript/reference/wallets/connect-wallet-option):

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

## Related

* [React UI components](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/overview.md): install the package and change its text and styles.
* [Connecting external wallets](https://www.dynamic.xyz/docs/javascript/building-ui/connecting-external-wallets.md): build the connection screens yourself.
* [Build a wallet picker](https://www.dynamic.xyz/docs/javascript/reference/wallets/build-wallet-picker.md): list every wallet a user can connect from the catalogue.
* [Flow payment widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/flow-widget.md): a payment widget that includes this wallet connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.