useContractReads

Hook for calling multiple read methods on a Contract.

This is a wrapper around viem's multicall.

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 publicClient must be set up as a chain-aware function for this to work correctly.

import { useContractReads } from 'wagmi'
import { optimism } from 'wagmi/chains'
 
function App() {
  const { data, isError, isLoading } = useContractReads({
    contracts: [
      {
        ...wagmigotchiContract,
        functionName: 'getAlive',
        chainId: optimism.id,
      },
      {
        ...wagmigotchiContract,
        functionName: 'getBoredom',
        chainId: optimism.id,
      },
    ],
  })
}

Note: The above example is using the optimism chain from the wagmi/chains entrypoint.

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,
  })
}

blockNumber (optional)

The block number to perform the read against.

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

blockTag (optional)

The block tag to perform the read against. Accepts: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'

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

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 (deprecated, optional)

Use structuralSharing instead.

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),
  })
}

structuralSharing (optional)

Keep referential identity of data and prevent rerenders. Defaults to (oldData, newData) => deepEqual(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData). If set to false, structural sharing between query results will be disabled.

If set to a function, the old and new data values will be passed through this function, which should combine them into resolved data for the query. This way, you can retain references from the old data to improve performance even when that data contains non-serializable values.

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

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