useReactorMethod

useReactorMethod is a unified hook for calling canister methods that automatically handles both query and mutation methods based on the Candid interface. It simplifies method calls by automatically determining whether to use useQuery or useMutation under the hood.

Features

Automatic Detection: Determines query vs mutation based on Candid annotations (query, composite_query).
Unified Interface: Same hook structure regardless of method type.
TypeScript Support: Full type safety for arguments and return types.
Cache Invalidation: Built-in support for invalidating queries after successful mutations.

Import

import { useReactorMethod } from "@ic-reactor/react"

Usage

Query Method (Auto-fetches)

For query methods, the hook behaves like useReactorQuery and fetches data on mount.

import { useReactorMethod } from "@ic-reactor/react"
import { reactor } from "./reactor"

function Balance({ owner }: { owner: string }) {
  const { data, isLoading, error } = useReactorMethod({
    reactor,
    functionName: "icrc1_balance_of",
    args: [{ owner }],
  })

  if (isLoading) return <div>Loading...</div>
  return <div>Balance: {data?.toString()}</div>
}

Mutation Method (Manual Call)

For update methods, the hook behaves like useReactorMutation. Data is only fetched when you call the call function.

import { useReactorMethod } from "@ic-reactor/react"
import { reactor } from "./reactor"

function Transfer() {
  const { call, isPending, data } = useReactorMethod({
    reactor,
    functionName: "transfer",
    invalidateQueries: [["icrc1_balance_of"]], // Optional: invalidate queries after success
  })

  const handleTransfer = async () => {
    await call([{ to: "recipient", amount: 100n }])
    alert("Transfer successful!")
  }

  return (
    <button onClick={handleTransfer} disabled={isPending}>
      {isPending ? "Transferring..." : "Transfer"}
    </button>
  )
}

Options

UseReactorMethodParameters extends react-query’s QueryObserverOptions, giving you access to all standard react-query options plus our custom reactor options.

Custom Options

Option	Type	Description
`reactor`	`Reactor<A, T>`	Required. The reactor instance to use.
`functionName`	`M`	Required. The method name to call on the canister.
`args`	`ReactorArgs<A, M, T>`	Arguments to pass to the method.
`callConfig`	`CallConfig`	Agent call configuration (e.g., `effectiveCanisterId`).
`queryKey`	`QueryKey`	Custom query key for queries.
`onSuccess`	`(data) => void`	Callback when the method call succeeds.
`onError`	`(error) => void`	Callback when the method call fails.
`invalidateQueries`	`QueryKey[]`	For mutations: keys to invalidate after success.

Inherited from React Query

All react-query options are available:

Option	Type	Default	Description
`enabled`	`boolean`	`true`	For queries: whether to auto-fetch.
`staleTime`	`number`	`300000`	How long data stays fresh (ms).
`gcTime`	`number`	`300000`	Time before unused data is garbage collected (ms).
`refetchInterval`	`number \| false`	`false`	Polling interval in ms.
`refetchOnWindowFocus`	`boolean`	`true`	Refetch when window regains focus.
`refetchOnMount`	`boolean`	`true`	Refetch when component mounts.
`refetchOnReconnect`	`boolean`	`true`	Refetch when network reconnects.
`retry`	`number \| boolean`	`3`	Number of retry attempts.
`retryDelay`	`number \| function`	exponential	Delay between retries.
`networkMode`	`string`	`"online"`	Network mode (`"online"`, `"always"`, `"offlineFirst"`).
`placeholderData`	`TData \| function`	-	Placeholder data while loading.

Return Value

Property	Type	Description
`data`	`ReactorReturnOk<A, M, T> \| undefined`	The returned data from the method call.
`call`	`(args?) => Promise<data>`	Function to trigger the method call manually.
`isLoading`	`boolean`	Whether the method is currently executing (alias for `isPending`).
`isPending`	`boolean`	Whether the method is currently executing.
`isError`	`boolean`	Whether the last call resulted in an error.
`isSuccess`	`boolean`	Whether the method has completed successfully.
`error`	`ReactorReturnErr<A, M, T> \| null`	The error object if one occurred.
`isQuery`	`boolean`	`true` if it’s a query method, `false` otherwise.
`functionType`	`FunctionType`	`"query"`, `"update"`, or `"composite_query"`.
`reset`	`() => void`	Clears the state (data and error).
`refetch`	`() => Promise`	For queries: manually refetches the data.
`queryResult`	`UseQueryResult`	The raw result if it’s a query.
`mutationResult`	`UseMutationResult`	The raw result if it’s a mutation.