Wallet Management

Configure wallet connections or bring your own wallet UI

The widget supports three virtual machine ecosystems: EVM, Solana (SVM), and Starknet. For each, you can either let the widget manage wallet connections itself or provide your own wallet UI.

Using the built-in wallet modal

By default, the widget sets up wallet providers and renders its own wallet selection modal.

• EVM — Creates a minimal Wagmi config. Discovers installed wallets via EIP-6963 and includes a WalletConnect fallback.
• SVM — Wraps itself in a Solana ConnectionProvider and WalletProvider.
• Starknet — Provides a default StarknetConfig with Braavos and Argent connectors.

Providing your own wallet providers

If your app already has wallet providers set up (e.g. a WagmiProvider higher in the tree), wrap the widget with WidgetExternalWalletProvider. This initializes the widget runtime and state without installing the widget's default wallet providers, so wallet hooks read from your existing contexts.

import { Widget } from "@superbridge/widget";
import { internals } from "@superbridge/widget/internals";

const { WidgetExternalWalletProvider } = internals;

function Bridge() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <WidgetExternalWalletProvider>
        <Widget />
      </WidgetExternalWalletProvider>
    </WagmiProvider>
  );
}

When you support Solana or Starknet routes, make sure the matching Solana wallet adapter or Starknet provider is also present above WidgetExternalWalletProvider.

Composing the default wallet providers

Apps that want to reuse the widget's default wallet providers while owning the surrounding wallet UI can compose the provider layers manually:

import { internals } from "@superbridge/widget/internals";

const {
  WidgetRuntimeProvider,
  WidgetStateProvider,
  WidgetView,
  WidgetWalletProvider,
} = internals;

function Bridge() {
  return (
    <WidgetRuntimeProvider>
      <WidgetWalletProvider>
        <WidgetStateProvider
          wallets={{
            openEvmWalletModal: () => openWalletDrawer(),
          }}
        >
          <WidgetView />
          <WalletDrawer />
        </WidgetStateProvider>
      </WidgetWalletProvider>
    </WidgetRuntimeProvider>
  );
}

Widget composes these layers for the default drop-in behavior.

Using your own wallet modal

If you want full control over the wallet connection UI, pass modal callbacks. When provided, the widget hides its built-in connect buttons for that ecosystem and calls your function instead.

<Widget
  openEvmWalletModal={() => {
    // Open your custom EVM wallet picker
  }}
  openSvmWalletModal={() => {
    // Open your custom Solana wallet picker
  }}
  openStarkWalletModal={() => {
    // Open your custom Starknet wallet picker
  }}
/>

You can mix and match — for example, provide your own EVM modal while letting the widget handle Solana and Starknet.