useContractWrite

Hook for calling an ethers Contract write method. Pairs with the usePrepareContractWrite hook.

import { useContractWrite } from 'wagmi'

Usage

The following examples use the wagmigotchi contract.

import { useContractWrite, usePrepareContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })
  const { data, isLoading, isSuccess, write } = useContractWrite(config)

  return (
    <div>
      <button disabled={!write} onClick={() => write?.()}>
        Feed
      </button>
      {isLoading && <div>Check Wallet</div>}
      {isSuccess && <div>Transaction: {JSON.stringify(data)}</div>}
    </div>
  )
}

💡

It is highly recommended to pair useContractWrite with the usePrepareContractWrite hook to avoid UX pitfalls.

Return Value

{
  data?: TransactionResponse
  error?: Error
  isError: boolean
  isIdle: boolean
  isLoading: boolean
  isSuccess: boolean
  write: ((args?: WriteContractConfig) => void) | undefined
  writeAsync: ((args?: WriteContractConfig) => Promise<TransactionResponse>) | undefined
  reset: () => void
  status: 'idle' | 'error' | 'loading' | 'success'
}

Configuration

mode

This is automatically populated when using usePrepareContractWrite hook.

recklesslyUnprepared: Allow to pass through an adhoc unprepared config. Note: This has UX pitfalls, it is highly recommended to not use this and instead prepare the config upfront using the usePrepareContractWrite hook.
prepared: The config has been prepared with parameters required for performing a contract write via the usePrepareContractWrite hook

import { useContractWrite } from 'wagmi'

function App() {
  const { sendTransaction } = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })
}

addressOrName

This is automatically populated when using usePrepareContractWrite hook.

Contract address or ENS name.

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })

  return <button onClick={() => write()}>Feed</button>
}

chainId (optional)

This is automatically populated when using usePrepareContractWrite hook.

Checks the current chain to make sure it is the same as chainId. If chainId is not the current chain, the connector attempts to switch to it before sending the transaction.

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    chainId: 1,
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })

  return <button onClick={() => write()}>Feed</button>
}

contractInterface

This is automatically populated when using usePrepareContractWrite hook.

Contract ABI in JSON or JS object format. An ethers Interface is also allowed.

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })

  return <button onClick={() => write()}>Feed</button>
}

functionName

This is automatically populated when using usePrepareContractWrite hook.

Name of function to call.

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
  })

  return <button onClick={() => write()}>Feed</button>
}

args (optional)

This is automatically populated when using usePrepareContractWrite hook.

Arguments to pass to function call. Accepts any | any[].

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
    args: [],
  })

  return <button onClick={() => write()}>Feed</button>
}

overrides (optional)

This is automatically populated when using usePrepareContractWrite hook.

Overrides to pass to function call.

import { useContractWrite } from 'wagmi'

function App() {
  const contractWrite = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'feed',
    overrides: {
      from: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
      value: ethers.utils.parseEther('0.01'),
    },
  })

  return <button onClick={() => write()}>Feed</button>
}

request (optional)

This is automatically populated when using usePrepareContractWrite hook.

The request to use when sending the contract transaction.

import { usePrepareContractWrite, useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({ ... })
  const { sendTransaction } = useContractWrite({
    ...config,
    request: config.request
  })
}

onError (optional)

Function to invoke when an error is thrown while attempting to write.

import { usePrepareContractWrite, useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({ ... })
  const { write } = useContractWrite({
    ...config,
    onError(error) {
      console.log('Error', error)
    },
  })
}

Function fires before the contract write function and is passed same variables the contract write function would receive. Value returned from this function will be passed to both onError and onSettled functions in event of a failure.

import { usePrepareContractWrite, useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({ ... })
  const { write } = useContractWrite({
    ...config,
    onMutate({ args, overrides }) {
      console.log('Mutate', { args, overrides })
    },
  })
}

onSettled (optional)

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

import { usePrepareContractWrite, useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({ ... })
  const { write } = useContractWrite({
    ...config,
    onSettled(data, error) {
      console.log('Settled', { data, error })
    },
  })
}

onSuccess (optional)

Function to invoke when write is successful.

import { usePrepareContractWrite, useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({ ... })
  const { write } = useContractWrite({
    ...config,
    onSuccess(data) {
      console.log('Success', data)
    },
  })
}

Override Config

It is possible to pass through override config. Any override config prefixed with recklesslySetUnprepared means that it will break the previously prepared config. It will need to prepare the request again at the time of invoking write/writeAsync.

💡

This usage is not recommended. It comes with UX pitfalls. Only use it as a last resort.

import { useContractWrite } from 'wagmi'

function App() {
  const { config } = usePrepareContractWrite({
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'claim',
  })
  const { data, isLoading, isSuccess, write } = useContractWrite(config)

  return (
    <div>
      <button
        disabled={!write}
        onClick={() =>
          write({
            recklesslySetUnpreparedArgs: 69,
            recklesslySetUnpreparedOverrides: {
              from: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
              value: ethers.utils.parseEther('0.01'),
            },
          })
        }
      >
        Claim
      </button>
      {isLoading && <div>Check Wallet</div>}
      {isSuccess && <div>Transaction: {JSON.stringify(data)}</div>}
    </div>
  )
}

Reckless Usage

It is possible to use useContractWrite without pairing it with usePrepareContractWrite by using "recklessly unprepared" mode.

💡

This usage is not recommended. It comes with UX pitfalls. Only use it as a last resort.

import { useContractWrite } from 'wagmi'

function App() {
  const { data, isLoading, isSuccess, write } = useContractWrite({
    mode: 'recklesslyUnprepared',
    addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
    contractInterface: wagmigotchiABI,
    functionName: 'claim',
    tokenId: 69,
  })

  return (
    <div>
      <button onClick={() => write()}>Claim</button>
      {isLoading && <div>Check Wallet</div>}
      {isSuccess && <div>Transaction: {JSON.stringify(data)}</div>}
    </div>
  )
}