useActorSuspenseQuery

useActorSuspenseQuery is a React hook for fetching data from canisters with Suspense support. It suspends the component until data is available, eliminating the need for loading state handling.

Import

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

const { useActorSuspenseQuery } = createActorHooks(backend)

Tip

It is recommended to rename the hooks to reflect the canister name, especially when working with multiple canisters:

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

const { useActorSuspenseQuery: useBackendSuspenseQuery } =
  createActorHooks(backend)

Usage

import { Suspense } from "react"
import { useActorSuspenseQuery } from "./reactor"

function UserProfile({ userId }: { userId: string }) {
  // This hook suspends until data is loaded
  const { data } = useActorSuspenseQuery({
    functionName: "get_user",
    args: [userId],
  })

  // data is ALWAYS defined here - no undefined check needed
  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  )
}

// Must be wrapped in Suspense
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <UserProfile userId="user-123" />
    </Suspense>
  )
}

Options

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

Same as useActorQuery except:

Caution

useActorSuspenseQuery does NOT support the enabled option. The query always executes immediately.

Key Options

Option	Type	Default	Description
functionName	string	Required	The canister method to call
args	array	[]	Arguments to pass to the method
staleTime	number	1000	Time in ms before data is considered stale. TanStack Query raises any lower value, 0 included, to 1 s
select	function	-	Transform the data before returning

Return Value

Returns a TanStack Query suspense result. The key difference from useActorQuery:

Property	Type	Description
data	TData	Always defined (never undefined)
error	TError | null	A failed first load is thrown to the Error Boundary. A failed refetch keeps data and sets this
status	'success' | 'error'	'error' after a failed refetch; the component suspends until there is data

Examples

Basic Suspense Query

import { Suspense } from "react"
import { useActorSuspenseQuery } from "./reactor"

function Greeting() {
  const { data } = useActorSuspenseQuery({
    functionName: "greet",
    args: ["World"],
  })

  // data is guaranteed to be defined
  return <h1>{data}</h1>
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Greeting />
    </Suspense>
  )
}

Multiple Suspense Queries

Two suspense queries in the same component run one after the other: the first hook suspends the component, so the second call starts only once the first has returned. Give each query its own component under one boundary and they start together:

import { Suspense } from "react"
import { useActorSuspenseQuery } from "./reactor"

function Dashboard({ userId }: { userId: string }) {
  // Sibling components suspend separately, so both calls start at once
  return (
    <Suspense fallback={<Loading />}>
      <Welcome userId={userId} />
      <UserStats userId={userId} />
    </Suspense>
  )
}

function Welcome({ userId }: { userId: string }) {
  const { data: user } = useActorSuspenseQuery({
    functionName: "get_user",
    args: [userId],
  })
  return <h1>Welcome, {user.name}</h1>
}

function UserStats({ userId }: { userId: string }) {
  const { data: stats } = useActorSuspenseQuery({
    functionName: "get_user_stats",
    args: [userId],
  })
  return <Stats data={stats} />
}

With Select

import { useActorSuspenseQuery } from "./reactor"

function Hello({ userId }: { userId: string }) {
  const { data: userName } = useActorSuspenseQuery({
    functionName: "get_user",
    args: [userId],
    select: (user) => user.name, // data is just the name string
  })

  return <h1>Hello, {userName}</h1>
}

Nested Suspense Boundaries

import { Suspense } from "react"

function App() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <Header /> {/* Has its own data */}
      <Suspense fallback={<ContentSkeleton />}>
        <MainContent /> {/* Independent loading */}
      </Suspense>
      <Suspense fallback={<SidebarSkeleton />}>
        <Sidebar /> {/* Independent loading */}
      </Suspense>
    </Suspense>
  )
}

Error Handling with Error Boundaries

import { Suspense } from "react"
import { ErrorBoundary, type FallbackProps } from "react-error-boundary"

function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div className="error">
      <p>Something went wrong:</p>
      <pre>{error instanceof Error ? error.message : String(error)}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  )
}

function App() {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <Suspense fallback={<Loading />}>
        <UserProfile userId="user-123" />
      </Suspense>
    </ErrorBoundary>
  )
}

With Stale Time

import { useActorSuspenseQuery } from "./reactor"

function Settings() {
  const { data } = useActorSuspenseQuery({
    functionName: "get_config",
    args: [],
    staleTime: 5 * 60 * 1000, // Fresh for 5 minutes
  })

  return <pre>{JSON.stringify(data)}</pre>
}

Sequential Suspense (Waterfall)

import { useActorSuspenseQuery } from "./reactor"

function UserPosts({ userId }: { userId: string }) {
  // This query runs first
  const { data: user } = useActorSuspenseQuery({
    functionName: "get_user",
    args: [userId],
  })

  // This query runs after user is loaded
  const { data: posts } = useActorSuspenseQuery({
    functionName: "get_user_posts",
    args: [user.id], // Uses data from first query
  })

  return <PostList posts={posts} author={user.name} />
}

Tip

To avoid waterfalls, fetch independent data in parallel using separate components or useSuspenseQueries (if available).

When to Use Suspense

✅ Use Suspense when:

• You always need the data (no conditional fetching)
• You want cleaner components without loading state
• You want loading states at the boundary level

❌ Use regular useActorQuery when:

• You need conditional fetching (enabled option)
• You want per-component loading UI
• You need to access isPending or isFetching states

Notes

Caution

An update method passed here runs on the canister again on every refetch (mount, window focus, reconnect, invalidation) and retry, each time as a new call. Use it only for an update method that is safe to repeat, and use useActorMutation or useActorMethod for a method that changes state. With no retry hook option set, an update method retries only a SysTransient rejection, which proves the call never ran. See Update Methods in Queries.

Note

Suspense queries throw errors instead of returning them. Always wrap in an Error Boundary to catch and display errors gracefully.

Note

args does not take skipToken: a suspense query has to be able to run. Mount the component only once its arguments exist, or use useActorQuery, which does.

Tip

With suspense, you can assume data is always defined in your component. This leads to cleaner code without null checks.

See Also

• useActorQuery — Regular query hook
• useActorSuspenseInfiniteQuery — Suspense pagination
• Queries Guide — In-depth query patterns
• createActorHooks — Creating hooks