Skip to main content

Build a Custom UI

Use the SDK to connect wallets to your app but use your own UI either manually or using the useConnect hook.

Create a Custom Connection

Connecting a wallet involves a few steps:

  1. Create a wallet instance
  2. Call the connect method on the wallet instance
  3. Set the connected wallet instance as "connected wallet"


If you just want to connect a wallet as mentioned above - there's a simple way to do it using the useConnect hook which does all the above steps for you.

Using useConnect hook
import {
// import the wallet you want to connect
} from "@thirdweb-dev/react";

const walletConfig = metamaskWallet();

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

async function handleConnect() {
try {
const wallet = await connect(
walletConfig, // pass the wallet config object
connectOptions, // pass options required by the wallet (if any)

console.log("connected to", wallet);
} catch (e) {
console.error("failed to connect", e);

return <button onClick={handleConnect}> connect wallet </button>;

Manually connect a wallet

If you need to create wallet instance and call some methods on the wallet instance before connecting the wallet, you can do these steps manually as shown below using the useCreateWalletInstance, useSetConnectionStatus and useSetConnectedWallet hooks.

Manually creating wallet instance and connecting

There are 3 steps to connect your wallet manually:

Make sure to update the connectionStatus using useSetConnectionStatus to "connecting" before connecting your wallet and "disconnected" if the connection fails.


We will use localWallet as an example because it can not be connected using the useConnect hook because it requires additional steps after creating the wallet instance - like generating a random wallet or importing a wallet. We will generate a random wallet in this example.

import {
// import the wallet you want to connect
} from "@thirdweb-dev/react";

const walletConfig = localWallet();

function Example() {
const createWalletInstance = useCreateWalletInstance();
const setConnectionStatus = useSetConnectionStatus();
const setConnectedWallet = useSetConnectedWallet();

const handleConnect = async () => {
// 1. create wallet instance
const wallet = createWalletInstance(walletConfig);

// perform additional steps that needs to be done before connecting the wallet
// here, we will generate a random wallet
await wallet.generate();

try {

// 2. Call `connect` method on wallet instance
await wallet.connect(
connectOptions, // pass options required by the wallet (if any)

// 3. Set wallet instance as the connected wallet
} catch (e) {
console.error("failed to connect", e);
// show error UI or close modal using props.close()

return <button onClick={handleConnect}> connect wallet </button>;

Once the wallet is connected, you can use React SDK's 100+ hooks to show the connected wallet's details, send transactions, interact with smart contracts, sign messages and utilize common standards such as tokens, NFTs, marketplaces; all with built-in caching, RPC URLs, IPFS gateways, and more!

The following hooks can be used with the connected wallet:

useAddressget connected wallet's account address
useDisconnectdisconnect the connected wallet
useWalletget connected wallet instance
useWalletConfigget connected wallet's config
useConnectionStatusget status of wallet connection
useSignerget signer of connected wallet

Create a Wallet Connection UI (in ConnectWallet)

Customize the UI of one of the supported wallets when using the ConnectWallet component or add UI for a custom wallet configurator to add to the ConnectWallet component.


To create a custom UI for connecting your wallet, create a connectUI function in your wallet configurator.

// optional - render a UI for connecting your wallet
connectUI(props) {
return <MyWalletConnectionUI {...props} />;


To create a custom UI for selecting your wallet in the wallet selection screen in the connect wallet modal, create a selectUI function in your wallet configurator.

    // optional - override the default UI for selecting your wallet in the wallet selector screen
selectUI(props) {
return <MyWalletSelectionUI {...props} />