Web3Modal react usage

Getting Started

Make sure to read our main readme first to find out details about projectId, chain specific packages and modal customisation options. Please ensure you are updated to the latest React / Next.js or similar version, as web3modal libraries target es2020. Web3Modal hooks are based on wagmi, so it is good idea to read through their documentation as well. Do note, you have to import and use these hooks from @web3modal packages.

1. Install dependencies

npm install @web3modal/react @web3modal/ethereum ethers

2. Configure web3modal at the root of your app

See @web3modal/ethereum readme for all available ethereum options. NextJS example is also available in examples/react folder.

import { Web3Modal } from '@web3modal/react'

const config = {
  projectId: '<YOUR_PROJECT_ID>',
  theme: 'dark',
  accentColor: 'default',
  ethereum: {
    appName: 'web3Modal'
  }
}

export default function App() {
  return (
    <>
      <YourAppContent />
      <Web3Modal config={config} />
    </>
  )
}

3. Add component or useConnectModal hook to open the modal

import { Web3Button, useConnectModal } from '@web3modal/react'

export default function YourAppContent() {
  const { isOpen, open, close } = useConnectModal()

  return (
    <>
      <Web3Button />
      {/* or */}
      <button onClick={open}>Open Modal</button>
    </>
  )
}

Modal Hooks

Hooks to manage web3modal.

useConnectModal

Hook to check state of the modal, open or close it.

import { useConnectModal } from '@web3modal/react'

// Usage
const { isOpen, open, close } = useConnectModal()

// Returns
interface Return {
  isOpen: boolean
  open: () => void
  close: () => void
}

Data Hooks

Hooks that return blockchain, account or network data. By default these automatically retrieve data for currently active network (chainId) one time when they are mounted. You can tweak this behaviour with following shared options (where available).

interface Options {
  // Specify concrete chainId for which to retrieve data, defaults to currently selected chain id
  chainId?: number

  // Specify whether hook should retrieve data when mounted or not, defaults to true
  enabled?: boolean

  // Specify whether hook should continuously watch for new data (every block). This uses websocket if available or falls back to pooling, default false
  watch?: boolean
}

useAccount (Example)

Hook to get account data.

import { useAccount } from '@web3modal/react'

// Usage
const { account, isReady } = useAccount()

// Returns
interface Return {
  account: {
    address: string | ''
    connector?: Connector
    isConnecting?: boolean
    isReconnecting?: boolean
    isConnected?: boolean
    isDisconnected?: boolean
    status?: 'connecting' | 'reconnecting' | 'connected' | 'disconnected'
  }
  isReady: boolean
}

useBalance (Example)

Hook for fetching balance information for Ethereum or ERC-20 tokens.

import { useBalance } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useBalance({ addressOrName: 'vitalik.eth' })

// Returns
interface Return {
  data?: {
    decimals: number
    formatted: string
    symbol: string
    value: BigNumber
  }
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  addressOrName: string
  watch?: boolean
  enabled?: boolean
  chainId?: number
  formatUnits?: number | 'wei' | 'kwei' | 'mwei' | 'gwei' | 'szabo' | 'finney' | 'ether'
  token?: string
}

useBlockNumber (Example)

Hook for fetching the current block number.

import { useBlockNumber } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useBlockNumber({ watch: true })

// Returns
interface Return {
  data?: number
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  watch?: boolean
  enabled?: boolean
  chainId?: number
}

useContract (Example)

Hook for declaratively creating an ethers Contract instance.

import { useContract } from '@web3modal/react'
import ensRegistryABI from './yourAbi/ensRegistryABI.json'

// Usage
const { contract, isReady } = useContract({
  address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
  abi: ensRegistryABI
})

// Returns
ethers.Contract | undefined

// Options
interface Options {
  contract?: {
    address: string
    abi: ContractInterface
    signerOrProvider?: Provider | Signer
  }
  isReady: boolean
}

useContractEvent (Example)

Hook for subscribing to ethers Contract events.

import { useContractEvent } from '@web3modal/react'
import ensRegistryABI from './yourAbi/ensRegistryABI.json'

// Usage
useContractEvent({
  address: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e',
  abi: ensRegistryABI,
  eventName: 'NewOwner',
  listener: (...event) => console.log(event)
})

// Options
interface Options {
  address: string
  abi: ContractInterface
  eventName: string
  listener: (...event: unknown[]) => void
  chainId?: number
  once?: boolean
}

useContractRead (Example)

Hook for calling an ethers Contract read-only method.

import { useContractRead } from '@web3modal/react'
import wagmigotchiABI from './yourAbi/wagmigotchiABI.json'

// Usage
const { data, error, isLoading, refetch } = useContractRead({
  address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
  abi: wagmigotchiABI,
  functionName: 'getHunger'
})

// Returns
interface Return {
  data?: Result
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  address: string
  abi: ContractInterface
  functionName: string
  args?: any[]
  overrides?: CallOverrides
  chainId?: number
  enabled?: boolean
  watch?: boolean
}

useEnsAddress (Example)

Hook for fetching address for ENS name.

import { useEnsAddress } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useEnsAddress({
  name: 'vitalik.eth'
})

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  name: string
  chainId?: number
  enabled?: boolean
}

useEnsAvatar (Example)

Hook for fetching avatar for ENS name.

import { useEnsAvatar } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useEnsAvatar({
  addressOrName: 'vitalik.eth'
})

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  addressOrName: string
  chainId?: number
  enabled?: boolean
}

useEnsName (Example)

Hook for fetching ENS name for address.

import { useEnsName } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useEnsName({
  address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
})

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  address: string
  chainId?: number
  enabled?: boolean
}

useEnsResolver (Example)

Hook for fetching the resolver for ENS name.

import { useEnsResolver } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useEnsResolver({
  name: 'vitalik.eth'
})

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  name: string
  chainId?: number
  enabled?: boolean
}

useFeeData (Example)

Hook for fetching network fee information.

import { useFeeData } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useFeeData({ formatUnits: 'gwei' })

// Returns
interface Return {
  data?: {
    gasPrice: BigNumber
    maxFeePerGas: BigNumber
    maxPriorityFeePerGas: BigNumber
    formatted: {
      gasPrice: string
      maxFeePerGas: string
      maxPriorityFeePerGas: string
    }
  }
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  formatUnits?: number | 'wei' | 'kwei' | 'mwei' | 'gwei' | 'szabo' | 'finney' | 'ether'
  chainId?: number
  watch?: boolean
  enabled?: boolean
}

useNetwork (Example)

Hook for accessing network data, such as current connected chain and connector chains.

import { useNetwork } from '@web3modal/react'

// Usage
const { network, isReady } = useNetwork()

// Returns
interface Return {
  network?: {
    chain?: Chain & { unsupported?: boolean }
    chains?: Chain[]
  }
  isReady: boolean
}

useProvider (Example)

Hook for accessing Client's ethers Provider.

import { useProvider } from '@web3modal/react'

// Usage
const { provider, isReady } = useProvider(options)

// Returns
interface Return {
  provider?: ethers.Provider
  isReady: boolean
}

interface Options {
  chainId?: number
}

useWebsocketProvider (Example)

Hook for accessing the Client's ethers WebSocket Provider.

import { useWebsocketProvider } from '@web3modal/react'

// Usage
const { websocketProvider, isReady } = useWebsocketProvider()

// Returns
interface Return {
  websocketProvider?: ethers.WebSocketProvider
  isReady: boolean
}

useSigner (Example)

Hook for accessing ethers Signer object for connected account.

import { useSigner } from '@web3modal/react'

// Usage
const { data, error, isLoading } = useSigner(options)

// Returns
interface Return {
  data?: ethers.providers.JsonRpcSigner
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

interface Options {
  chainId?: number
}

useToken (Example)

Hook for fetching ERC-20 token information.

import { useToken } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useToken({
  address: '0xc18360217d8f7ab5e7c516566761ea12ce7f9d72'
})

// Returns
interface Return {
  data?: {
    address: string
    decimals: number
    name: string
    symbol: string
    totalSupply: {
      formatted: string
      value: BigNumber
    }
  }
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  address: string
  chainId?: number
  enabled?: boolean
  formatUnits?: number | 'wei' | 'kwei' | 'mwei' | 'gwei' | 'szabo' | 'finney' | 'ether'
}

useTransaction (Example)

Hook for fetching transaction by hash.

import { useTransaction } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useTransaction({
  hash: '0xe75fb554e433e03763a1560646ee22dcb74e5274b34c5ad644e7c0f619a7e1d0'
})

// Returns
interface Return {
  data?: TransactionResponse
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  hash: string
  chainId?: number
  enabled?: boolean
}

useWaitForTransaction (Example)

Hook for declaratively waiting until transaction is processed. Pairs well with useContractWrite and useSendTransaction.

import { useWaitForTransaction } from '@web3modal/react'

// Usage
const { data, error, isLoading, refetch } = useWaitForTransaction({
  hash: '0xe75fb554e433e03763a1560646ee22dcb74e5274b34c5ad644e7c0f619a7e1d0'
})

// Returns
interface Return {
  data?: TransactionResponse
  error?: Error
  isLoading: boolean
  refetch: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  confirmations?: number
  hash?: string
  timeout?: number
  chainId?: number
  enabled?: boolean
}

Action Hooks

Hooks that expose action / write opperations.

useContractWrite (Example)

Hook for calling an ethers Contract write method. Perpares transaction under the hood i.e. estimates gas price.

import { useContractWrite } from '@web3modal/react'
import wagmigotchiABI from './yourAbi/wagmigotchiABI.json'

// Usage
const { data, error, isLoading, write } = useContractWrite({
  address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
  abi: wagmigotchiABI,
  functionName: 'feed'
})
write()

// Returns
interface Return {
  data?: TransactionResponse
  error?: Error
  isLoading: boolean
  write: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  functionName: string
  chainId?: number | undefined
  args?: any[]
  overrides?: CallOverrides
  signer?: Signer
}

useDisconnect

Hook for disconnecting the connected account.

import { useDisconnect } from '@web3modal/react'

// Usage
const disconnect = useDisconnect()
disconnect()

// Returns
() => void

useSendTransaction (Example)

Hook for sending a transaction. Perpares transaction under the hood i.e. estimates gas price.

import { useSendTransaction } from '@web3modal/react'
import { BigNumber } from 'ethers'

// Usage
const { data, error, isLoading, sendTransaction } = useSendTransaction({
  request: {
    to: 'vitalik.eth',
    value: BigNumber.from('10000000000000000')
  }
})
sendTransaction()

// Returns
interface Return {
  data?: TransactionResponse
  error?: Error
  isLoading: boolean
  sendTransaction: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  request: TransactionRequest & {
    to: string
  }
  chainId?: number
  signer?: Signer
}

useSignMessage (Example)

Hook for signing messages with connected account.

import { useSignMessage } from '@web3modal/react'

// Usage
const { data, error, isLoading, signMessage } = useSignMessage({
  message: 'WalletConnect web3modal message'
})
signMessage()

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  signMessage: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  message: string | Bytes
}

useSignTypedData (Example)

Hook for signing messages with connected account.

import { useSignTypedData } from '@web3modal/react'

// Usage
const { data, error, isLoading, signTypedData } = useSignTypedData({
  domain,
  types,
  value
})
signTypedData()

// Returns
interface Return {
  data?: string
  error?: Error
  isLoading: boolean
  signTypedData: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  domain: {
    name?: string
    version?: string
    chainId?: string | number | bigint
    verifyingContract?: string
    salt?: BytesLike
  }
  types: Record<
    string,
    Array<{
      name: string
      type: string
    }>
  >
  value: Record<string, any>
}

useSwitchNetwork (Example)

Hook for switching networks with a connector.

import { useSwitchNetwork } from '@web3modal/react'

// Usage
const { data, error, isLoading, switchNetwork } = useSwitchNetwork({
  chainId: 1
})
switchNetwork()

// Returns
interface Return {
  data?: Chain
  error?: Error
  isLoading: boolean
  switchNetwork: (options?: Options) => Promise<Return['data']>
}

// Options
interface Options {
  chainId?: number
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

react.md

react.md

Web3Modal react usage

Getting Started

1. Install dependencies

2. Configure web3modal at the root of your app

3. Add component or useConnectModal hook to open the modal

Modal Hooks

useConnectModal

Data Hooks

useAccount (Example)

useBalance (Example)

useBlockNumber (Example)

useContract (Example)

useContractEvent (Example)

useContractRead (Example)

useEnsAddress (Example)

useEnsAvatar (Example)

useEnsName (Example)

useEnsResolver (Example)

useFeeData (Example)

useNetwork (Example)

useProvider (Example)

useWebsocketProvider (Example)

useSigner (Example)

useToken (Example)

useTransaction (Example)

useWaitForTransaction (Example)

Action Hooks

useContractWrite (Example)

useDisconnect

useSendTransaction (Example)

useSignMessage (Example)

useSignTypedData (Example)

useSwitchNetwork (Example)

Files

react.md

Latest commit

History

react.md

File metadata and controls

Web3Modal react usage

Getting Started

1. Install dependencies

2. Configure web3modal at the root of your app

3. Add component or useConnectModal hook to open the modal

Modal Hooks

useConnectModal

Data Hooks

useAccount (Example)

useBalance (Example)

useBlockNumber (Example)

useContract (Example)

useContractEvent (Example)

useContractRead (Example)

useEnsAddress (Example)

useEnsAvatar (Example)

useEnsName (Example)

useEnsResolver (Example)

useFeeData (Example)

useNetwork (Example)

useProvider (Example)

useWebsocketProvider (Example)

useSigner (Example)

useToken (Example)

useTransaction (Example)

useWaitForTransaction (Example)

Action Hooks

useContractWrite (Example)

useDisconnect

useSendTransaction (Example)

useSignMessage (Example)

useSignTypedData (Example)

useSwitchNetwork (Example)