useContractReads

Hook for calling multiple ethers Contract read-only methods.

import { useContractReads } from 'wagmi'

Usage

The following examples use the wagmigotchi & more loot contracts.

import { useContractReads } from 'wagmi'
 
const wagmigotchiContract = {
  address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
  abi: wagmigotchiABI,
}
const mlootContract = {
  address: '0x1dfe7ca09e99d10835bf73044a23b73fc20623df',
  abi: mlootABI,
}
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
      {
        ...mlootContract,
        functionName: 'getChest',
        args: [69],
      },
      {
        ...mlootContract,
        functionName: 'getWaist',
        args: [69],
      },
    ],
  })
}

Return Value

{
  data?: Result[]
  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<Result>
  status: 'idle' | 'error' | 'loading' | 'success'
}

Configuration

contracts

address (optional)

Contract address. Hook will not run unless address is defined for all contracts.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getAlive',
      },
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getBoredom',
      },
    ],
  })
}

abi (optional)

Contract ABI. Hook will not run unless abi is defined for all contracts.

By defining inline or adding a const assertion to abi, TypeScript will infer the correct types for functionName, args, and hook result. See the wagmi TypeScript docs for more information.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getAlive',
      },
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getBoredom',
      },
    ],
  })
}

functionName (optional)

Name of function to call. Hook will not run unless functionName is defined for all contracts.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getAlive',
      },
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getBoredom',
      },
    ],
  })
}

args (optional)

Arguments to pass to function call.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        address: '0x1dfe7ca09e99d10835bf73044a23b73fc20623df',
        abi: mlootABI,
        functionName: 'getChest',
        args: [69],
      },
      {
        address: '0x1dfe7ca09e99d10835bf73044a23b73fc20623df',
        abi: mlootABI,
        functionName: 'getWaist',
        args: [69],
      },
    ],
  })
}

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 { useContractReads, chain } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
        chainId: chain.mainnet.id,
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
        chainId: chain.mainnet.id,
      },
    ],
  })
}

allowFailure (optional)

If a contract read fails while fetching, it will fail silently and not throw an error.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    allowFailure: false,
  })
}

overrides (optional)

Overrides to pass to function call.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    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 { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    cacheOnBlock: true,
  })
}

watch (optional)

Watches and refreshes data for new blocks.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    watch: true,
  })
}

cacheTime (optional)

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

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    cacheTime: 2_000,
  })
}

enabled (optional)

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

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    enabled: false,
  })
}

isDataEqual (optional)

Determines if the data has changed or not. Defaults to deepEqual.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    isDataEqual: (prev, next) => prev === next,
  })
}

scopeKey (optional)

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

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    scopeKey: 'wagmi',
    contracts: [
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getAlive',
      },
      {
        address: '0xecb504d39723b0be0e3a9aa33d646642d1051ee1',
        abi: wagmigotchiABI,
        functionName: 'getBoredom',
      },
    ],
  })
}

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 { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    staleTime: 2_000,
  })
}

select (optional)

Transform or select a part of the data returned by the contract.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    select: (data) => transform(data),
  })
}

suspense (optional)

Set this to true to enable suspense mode.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    suspense: true,
  })
}

onSuccess (optional)

Function to invoke when fetching new data is successful.

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    onSuccess(data) {
      console.log('Success', data)
    },
  })
}

onError (optional)

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

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    onError(error) {
      console.log('Error', error)
    },
  })
}

onSettled (optional)

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

import { useContractReads } from 'wagmi'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
      },
    ],
    onSettled(data) {
      console.log('Settled', data)
    },
  })
}

useContractRead useContractWrite