@web3modal/react

@web3modal/react

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 version.

1. Install dependencies

npm install @web3modal/react @web3modal/ethereum ethers

2. Configure wagmi and web3modal clients 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 type { ConfigOptions } from '@web3modal/react'
import { Web3ModalProvider } from '@web3modal/react'

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

export default function App() {
  return <Web3ModalProvider config={config}>{/* Rest of your app */}</Web3ModalProvider>
}

Hooks

Please refer to hooks folder for more detailed info abut usage and argument / return types.

useConnectModal

Hook to open, close and check state of the connect modal

import { useConnectModal } from '@web3modal/react'

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

useAccount

Hook to get account data

import { useAccount } from '@web3modal/react'

const { chainSupported, address, chainId, connector } = useAccount()

useBalance

Hook to get account data

import { useBalance } from '@web3modal/react'

interface Options {
  addressOrName: string
  chainId: string // CAIP format i.e. Ethereum would be eip155:1
  formatUnits: FetchBalanceArgs['formatUnits']
}

const { refetch, isLoading, error, balance } = useBalance(options)

useNetwork

Hook to get network data

import { useNetwork } from '@web3modal/react'

const { chain, chains } = useNetwork()

useSigner

Hook to get ethers signer

import { useSigner } from '@web3modal/react'

const { refetch, isLoading, error, signer } = useSigner()

useSignMessage

Hook to crate and handle sign message request

import { useSignMessage } from '@web3modal/react'

const { isLoading, error, signature, sign } = useSignMessage()

useSignTypedData

Hook to crate and handle sign typed data request

import { useSignTypedData } from '@web3modal/react'

const { isLoading, error, signature, sign } = useSignTypedData()

useSwitchNetwork (⚠️ experimental)

Hook to switch between supported networks

import { useSwitchNetwork } from '@web3modal/react'

const { isLoading, error, chainId, switchChain } = useSwitchNetwork()

useContract

Hook to get contract details

import { useContract } from '@web3modal/react'

interface Options {
  addressOrName: string
  contractInterface: GetContractArgs['contractInterface']
  signerOrProvider: GetContractArgs['signerOrProvider']
}

const { refetch, error, contract } = useContract(options)

useContractEvent

Hook to subscribe / receive contract events

import { useContractEvent } from '@web3modal/react'

interface Options {
  addressOrName: string
  contractInterface: GetContractArgs['contractInterface']
  signerOrProvider: GetContractArgs['signerOrProvider']
  event: string
  handler: (args: unknown[]) => void
  once: boolean
}

const { refetch, error, contract } = useContractEvent(options)

useContractRead

Hook to read from contract

import { useContractRead } from '@web3modal/react'

interface Options {
  addressOrName: string
  functionName: string
  contractInterface: ReadContractConfig['contractInterface']
  args: unknown
  chainId: string
  overrides: ReadContractConfig['overrides']
}

const { refetch, isLoading, error, read } = useContractRead(options)

useContractWrite

Hook to write to contract

import { useContractWrite } from '@web3modal/react'

interface Options {
  addressOrName: string
  functionName: string
  contractInterface: ReadContractConfig['contractInterface']
  args: unknown
  chainId: string
  overrides: ReadContractConfig['overrides']
  request: Exclude<WriteContractArgs['request'], undefined>
}

const { data, refetch, isLoading, error } = useContractWrite(options)

usePrepareContractWrite

Hook to prepare for contract write

import { usePrepareContractWrite } from '@web3modal/react'

interface Options {
  addressOrName: string
  functionName: string
  contractInterface: ReadContractConfig['contractInterface']
  args: unknown
  chainId: string
  overrides: ReadContractConfig['overrides']
  request: Exclude<WriteContractArgs['request'], undefined>
}

const { write, refetch, isLoading, error } = usePrepareContractWrite(options)

useToken

Hook to get token data

import { useToken } from '@web3modal/react'

interface Options {
  address: string
  chainId: string
  formatUnits: FetchTokenArgs['formatUnits']
}

const { refetch, isLoading, error, token } = useToken(options)

useWatchReadContract

Hook to read and watch contract

import { useWatchReadContract } from '@web3modal/react'

interface Options {
  callback: WatchReadContractResult
  listenToBlock: boolean
}

useWatchReadContract(options)

useFetchEnsAddress

Hook to fetch public address from ens address

import { useFetchEnsAddress } from '@web3modal/react'

interface Options {
  chainId: string
  name: string
}

const { refetch, isLoading, error, address } = useFetchEnsAddress(options)

useFetchEnsAvatar

Hook to fetch ens avatar

import { useFetchEnsAvatar } from '@web3modal/react'

interface Options {
  chainId: string
  addressOrName: string
}

const { refetch, isLoading, error, avatar } = useFetchEnsAvatar(options)

useFetchEnsName

Hook to fetch ens name for public address

import { useFetchEnsName } from '@web3modal/react'

interface Options {
  chainId: string
  address: string
}

const { refetch, isLoading, error, name } = useFetchEnsName(options)

useFetchEnsResolver

Hook to get contract address for ens name resolver

import { useFetchEnsResolver } from '@web3modal/react'

interface Options {
  chainId: string
  name: string
}

const { refetch, isLoading, error, address } = useFetchEnsResolver(options)

useFetchTransaction

Hook to fetch a transaction

import { useFetchTransaction } from '@web3modal/react'

interface Options {
  chainId: string
  hash: FetchTransactionArgs['hash']
}

const { refetch, isLoading, error, transaction } = useFetchTransaction(options)

usePrepareSendTransaction

Hook to prepare send transaction request

import { usePrepareSendTransaction } from '@web3modal/react'

interface Options {
  chainId: string
  request: PrepareSendTransactionArgs['request']
  signerOrProvider?: PrepareSendTransactionArgs['signerOrProvider']
}

const { refetch, isLoading, error, transaction } = usePrepareSendTransaction(options)

useSendTransaction

Hook to send transaction

import { useSendTransaction } from '@web3modal/react'

interface Options {
  chainId: string
  request: SendTransactionArgs['request'] & {
    to: `0x${string}`
    gasLimit?: Exclude<SendTransactionArgs['request']['gasLimit'], undefined>
  }
}

const { refetch, isLoading, error, transaction } = useSendTransaction(options)

useWaitForTransaction

Hook to send transaction

import { useWaitForTransaction } from '@web3modal/react'

interface Options {
  chainId: string
  confirmation?: number
  hash?: string
  timeout?: number
  wait?: WaitForTransactionArgs['wait']
}

const { refetch, isLoading, error, transaction } = useWaitForTransaction(options)