Skip to main content

walletConnect

A wallet configurator for Wallet Connect v2 which allows integrating the wallet with React

import { walletConnect } from "@thirdweb-dev/react";

const walletConnectConfig = walletConnect(options);
customize (optional)

walletConnectConfig contains the default config for metadata and UI. you can optionally choose to override the defaults to customize the wallet. Learn more about these configs

const walletConnectConfig = walletConnect({ ... });

// override metadata
walletConnectConfig.meta.name = "..."; // change the name
walletConnectConfig.meta.iconURL = "..."; // change the icon
walletConnectConfig.meta.urls = {
  // change urls to download the wallet on various platforms
  android: "https://...",
  ios: "https://...",
  chrome: "https://...",
  firefox: "https://...",
};

// override connection UI
walletConnectConfig.connectUI = WalletConnectConnectUI; // react component

// custom selection UI
walletConnectConfig.selectUI = WalletConnectSelectUI; // react component

Once the config is ready, you can use it with ConnectWallet component or useConnect hook as shown below

// add to ThirdwebProvider to add it in ConnectWallet's modal
<ThirdwebProvider supportedWallets={[walletConnectConfig]} clientId="your-client-id"/>;

// or use it with useConnect hook
const connect = useConnect();
connect(walletConnectConfig, { ... });

options​

projectId (recommended)

Your project's unique identifier that can be obtained at cloud.walletconnect.com. It is highly recommended to use your own project id and only use the default one for testing purposes.

It Enables following functionalities within Web3Modal:

  • wallet and chain logos,
  • optional WalletConnect RPC,
  • support for all wallets from our Explorer and WalletConnect v2 support.

Defaults to thirdweb's common project id.

import { WalletConnect } from "@thirdweb-dev/wallets";

const wallet = new WalletConnect(
  {
    projectId: "<PROJECT_ID>",
  },
);
qrModalOptions (optional)

WalletConnect's options to customize the QR Code Modal.

type QRModalOptions = {
  themeVariables?: {
    "--wcm-z-index"?: string;
    "--wcm-accent-color"?: string;
    "--wcm-accent-fill-color"?: string;
    // ... and more
  };
  themeMode?: "dark" | "light";
  standaloneChains?: string[];
  mobileWallets?: MobileWallet[];
  desktopWallets?: DesktopWallet[];
  walletImages?: Record<string, string>;
  chainImages?: Record<string, string>;
  tokenImages?: Record<string, string>;
  tokenContracts?: Record<number, string>;
  enableNetworkView?: boolean;
  enableAccountView?: boolean;
  enableExplorer?: boolean;
  explorerRecommendedWalletIds?: string[] | "NONE";
  explorerExcludedWalletIds?: string[] | "ALL";
  termsOfServiceUrl?: string;
  privacyPolicyUrl?: string;
};

interface MobileWallet {
  id: string;
  name: string;
  links: {
    universal: string;
    native?: string;
  };
}

interface DesktopWallet {
  id: string;
  name: string;
  links: {
    native: string;
    universal: string;
  };
}
themeVariables

Allows to override Web3Modal's css styles. See theming for Info.

themeMode

Puts Modal into dark or light mode. Defaults to user's system preference.

standaloneChains

When using Web3Modal in standalone mode (without wagmi) you can define array of custom chains via this option.

Defaults to undefined

standaloneChains: [
  "eip155:1",
  "cosmos:cosmoshub-4",
  "polkadot:91b171bb158e2d3848fa23a9f1c25182",
];
mobileWallets

You can define an array of custom mobile wallets.

Note: you will also need to add appropriate wallet images in walletImages.

Native link represents deep-linking URL like rainbow:// and Universal link represent webpage link that can redirect to the app or fallback page. Defaults to undefined

mobileWallets: [
  {
    id: string,
    name: string,
    links: {
      native: string
      universal: string,
    },
  },
];
desktopWallets

You can define an array of custom desktop or web based wallets.

Note: you will also need to add appropriate wallet images in walletImages.

Native link represents deeplinking url like ledgerlive:// and Universal link represents webpage link that can redirect to the app or fallback page.

Defaults to undefined

desktopWallets: [
  {
    id: string,
    name: string,
    links: {
      native: string
      universal: string,
    },
  },
];
walletImages

Array of wallet id's and their logo mappings.

This will override default logos.

Id's in this case can be: Explorer id's, wallet id's you provided in mobileWallets or desktopWallets and Wagmi connector id's.

Defaults to undefined

walletImages: {
  rainbow: "/images/rainbow.webp",
  metaMask: "/images/metamask.webp",
};
chainImages

Array of chain id's and their logo mappings.

This will override default logos.

You can find detailed chain data at chainlist.org

Defaults to undefined

chainImages: {
  1: "/images/ethereum.webp",
  137: "/images/polygon.webp",
};
tokenImages

Array of token symbols and their logo mappings.

Defaults to undefined

tokenImages: {
  ETH: "/images/eth.webp",
  AVAX: "/images/avax.webp",
};
tokenContracts

Allows to override default token(s) address for each chain to show custom balances in account view.

Defaults to undefined

tokenContracts: {
  1: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',
  137: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
}
enableNetworkView

If more than 1 chain is provided in modal, users will be show network selection view before selecting a wallet.

This option can enable or disable this behavior.

Defaults to false

enableAccountView

Option to enable or disable the modal's account view.

default is true

enableExplorer

Option to enable or disable wallet fetching from Explorer.

Defaults to true

explorerRecommendedWalletIds

Allows to override default recommended wallets that are fetched from Explorer API.

You can define an array of wallet id's you'd like to prioritise (order is respected).

You can get / copy these id's from the explorer link mentioned before.

If you want to completely disable recommended wallets, you can set this option to "NONE".

Defaults to undefined

explorerRecommendedWalletIds: [
  "1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369",
  "4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0",
];
// -- or -- //
explorerRecommendedWalletIds: "NONE";
explorerExcludedWalletIds

Allows to exclude wallets that are fetched from Explorer API.

You can define an array of wallet id's you'd like to exclude.

You can get / copy these id's from the explorer link mentioned before.

If you want to exclude all wallets, you can set this option to "ALL", however if explorerRecommendedWalletIds are defined, they will still be fetched.

Defaults to undefined

explorerExcludedWalletIds: [
  "1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369",
  "4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0",
];
// -- or -- //
explorerExcludedWalletIds: "ALL";
termsOfServiceUrl

String URL to your terms of service page, if specified will append special "legal info" footer to the modal.

Defaults to undefined

privacyPolicyUrl

String URL to your privacy policy page, if specified will append special "legal info" footer to the modal.

Defaults to undefined

recommended (optional)

Show this wallet as "recommended" in the ConnectWallet Modal.

walletConnect({
  recommended: true,
});

Usage with ConnectWallet​

To allow users to connect to this wallet using the ConnectWallet component, you can add it to ThirdwebProvider's supportedWallets prop.

<ThirdwebProvider
  supportedWallets={[walletConnect()]}
  clientId="your-client-id"
>
  <YourApp />
</ThirdwebProvider>

Usage with useConnect​

you can use the useConnect hook to programmatically connect to the wallet without using the ConnectWallet component.

The wallet also needs to be added in ThirdwebProvider's supportedWallets if you want the wallet to auto-connect on next page load.

const walletConnectConfig = walletConnect();

function App() {
  const connect = useConnect();

  const handleConnect = async () => {
    await connect(walletConnectConfig, connectOptions);
  };

  return <div> ... </div>;
}

connectOptions​

{ chainId?: number } | undefined
chainId (optional)

If chainId is provided, wallet will be connected and immediately switch to network with given chainId.

Chain object corresponding to this chainId from @thirdweb-dev/chains package must be specified in ThirdwebProvider's supportedChains prop as shown below

import { Polygon } from "@thirdweb-dev/chains";
import { ThirdwebProvider } from "@thirdweb-dev/react";

export function YourApp() {
  return (
    <ThirdwebProvider supportedChains={[Polygon]} clientId="your-client-id">
      <App />
    </ThirdwebProvider>
  );
}