React Patterns

React Patterns

IC Reactor supports a few distinct React integration styles. Choosing the right one keeps your app simpler and avoids mixing component-only hooks with imperative code.

1. createActorHooks(...)

Use this when components can pass functionName and args inline.

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

export const { useActorQuery, useActorMutation, useActorMethod } =
  createActorHooks(backend)

Good fit:

• straightforward React apps
• one hook suite per canister
• minimal setup

2. Query and Mutation Factories

Use factories when the same operation must work both inside and outside React.

import { createQuery, createMutation } from "@ic-reactor/react"

export const getProfile = createQuery(backend, {
  functionName: "get_profile",
})

export const updateProfile = createMutation(backend, {
  functionName: "update_profile",
})

Inside React:

const { data } = getProfile.useQuery()
const mutation = updateProfile.useMutation({
  invalidateQueries: [getProfile.getQueryKey()],
})

Outside React:

await getProfile.fetch()
await updateProfile.execute([{ name: "Alice" }])

Good fit:

• route loaders and actions
• shared service modules
• targeted invalidation
• test helpers

3. Direct Reactor Hooks

Use useReactorQuery, useReactorMutation, and friends when you want to pass the reactor instance at call time instead of binding it upfront.

This is usually useful in shared abstractions or when the reactor is selected dynamically.

4. useActorMethod / useReactorMethod

Use these when a component wants one imperative interface that can handle query and update methods through call(...).

5. Reactor vs DisplayReactor

Use Reactor when you want raw Candid types:

• bigint
• Principal
• raw blobs

Use DisplayReactor when you want UI-friendly values:

• numeric values as strings
• principals as text
• friendlier inputs for forms

Rule of Thumb

• Components only: start with createActorHooks(...)
• Shared operations across React and non-React code: use factories
• Dynamic canister or runtime method work: use reactor hooks or candid packages