useWaitForTransaction

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

This is a wrapper around viem's waitForTransactionReceipt.

import { useWaitForTransaction } from 'wagmi'

Usage

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
  })
 
  if (isLoading) return <div>Processing…</div>
  if (isError) return <div>Transaction error</div>
  return <div>Transaction: {JSON.stringify(data)}</div>
}

💡

Hook does not run unless hash is defined.

Return Value

{
  data?: TransactionReceipt
  error?: Error
  isIdle: boolean
  isLoading: boolean
  isFetching: boolean
  isSuccess: boolean
  isError: boolean
  isFetched: boolean
  isFetchedAfterMount: boolean
  isRefetching: boolean
  refetch: (options: {
    throwOnError: boolean
    cancelRefetch: boolean
  }) => Promise<TransactionReceipt>
  status: 'idle' | 'error' | 'loading' | 'success'
}

Configuration

chainId (optional)

Force a specific chain id for waiting on transaction. The wagmi Client's publicClient must be set up as a chain-aware function for this to work correctly.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    chainId: 1,
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
  })
}

confirmations (optional)

Waits until confirmations number of blocks are mined on top of the block containing the transaction. Defaults to 1. If confirmations is 0, hook will not wait and return immediately without blocking, likely resulting in data being null.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    confirmations: 1,
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
  })
}

hash (optional)

Transaction hash to monitor. Works well with useContractWrite and useSendTransaction.

import {
  useContractWrite,
  usePrepareContractWrite,
  useWaitForTransaction,
} from 'wagmi'
 
function App() {
  const { config } = usePrepareContractWrite({
    address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    abi: wagmigotchiABI,
    functionName: 'feed',
  })
  const contractWrite = useContractWrite(config)
  const waitForTransaction = useWaitForTransaction({
    hash: contractWrite.data?.hash,
  })
}

timeout (optional)

Maximum amount of time to wait before timing out in milliseconds. Defaults to 0 (will wait until transaction processes).

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    timeout: 2_000, // 2 seconds
  })
}

cacheTime (optional)

Time (in ms) which the data should remain in the cache.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    cacheTime: 2_000,
  })
}

enabled (optional)

Set this to false to disable this query from automatically running. Defaults to true.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    enabled: false,
  })
}

scopeKey (optional)

Scopes the cache to a given context. Hooks that have identical context will share the same cache.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    scopeKey: 'wagmi',
  })
}

staleTime (optional)

Time (in ms) after data is considered stale. If set to Infinity the data will never be considered stale. Defaults to 0.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    staleTime: 2_000,
  })
}

suspense (optional)

Set this to true to enable suspense mode.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    suspense: true,
  })
}

onReplaced (optional)

Callback to invoke when the transaction has been sped up (replaced with higher gas fee values).

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    onReplaced(data) {
      console.log('Transaction has been sped up', data)
    },
  })
}

onSuccess (optional)

Function to invoke when fetching new data is successful.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    onSuccess(data) {
      console.log('Success', data)
    },
  })
}

onError (optional)

Function to invoke when an error is thrown while fetching new data.

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    onError(error) {
      console.log('Error', error)
    },
  })
}

onSettled (optional)

Function to invoke when fetching is settled (either successfully fetched, or an error has thrown).

import { useWaitForTransaction } from 'wagmi'
 
function App() {
  const waitForTransaction = useWaitForTransaction({
    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
    onSettled(data, error) {
      console.log('Settled', { data, error })
    },
  })
}

useTransaction useWalletClient