useContractRead

Docs

Hooks

useContractRead

Hook for calling an ethers Contract read-only method.

import { useContractRead } from 'wagmi'

Usage

The following examples use the wagmigotchi contract.

import { useContractRead } from 'wagmi'

function App() {
  const { data, isError, isLoading } = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
  )
}

Return Value

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

Arguments

contractConfig

See useContract for more info.

functionName

Name of function to call.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getSleep',
  )
}

Configuration

args (optional)

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

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'love',
    {
      args: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
    },
  )
}

chainId (optional)

Force a specific chain id for the request. The wagmi Client's ethers provider must be set up as a chain-aware function for this to work correctly.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      chainId: 1,
    },
  )
}

overrides (optional)

Overrides to pass to function call.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      overrides: { from: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e' },
    },
  )
}

cacheOnBlock (optional)

Caches & persists the return data against the current block. Data will be considered stale when a new block arrives.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      cacheOnBlock: true,
    },
  )
}

watch (optional)

Watches and refreshes data for new blocks.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      watch: true,
    },
  )
}

cacheTime (optional)

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

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      cacheTime: 2_000,
    },
  )
}

enabled (optional)

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

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      enabled: false,
    },
  )
}

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 { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      staleTime: 2_000,
    },
  )
}

suspense (optional)

Set this to true to enable suspense mode.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      suspense: true,
    },
  )
}

onSuccess (optional)

Function to invoke when fetching new data is successful.

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      onSuccess(data) {
        console.log('Success', data)
      },
    },
  )
}

onError (optional)

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

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      onError(error) {
        console.log('Error', error)
      },
    },
  )
}

onSettled (optional)

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

import { useContractRead } from 'wagmi'

function App() {
  const contractRead = useContractRead(
    {
      addressOrName: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
      contractInterface: wagmigotchiABI,
    },
    'getHunger',
    {
      onSettled(data, error) {
        console.log('Settled', { data, error })
      },
    },
  )
}

useContractEvent

useContractWrite