Chapter 69: useSuspenseQuery

Core Idea

Same options/returns as useQuery minus the three that don't make sense under Suspense (throwOnError, enabled, placeholderData) — data is guaranteed defined, status collapses to just 'success' | 'error', and cancellation doesn't work.

Key Concepts

• Removed options: throwOnError (suspense mode always throws to the boundary by design); enabled (can't conditionally suspend — see Suspense chapter for the workaround); placeholderData (no suspense equivalent).
• Return differences from useQuery: data is always defined at the type level; isPlaceholderData doesn't exist; status only ever reports 'success' or 'error' (never 'pending', since Suspense/the fallback handles that state instead).
• Caveat: query cancellation (Chapter 31) does not work with this hook.

Code Examples

const { data } = useSuspenseQuery({ queryKey, queryFn }) // data: Post (never undefined)

• What it demonstrates: the guaranteed-defined data this hook exists to provide.

Key Takeaways

1. Don't try to pass enabled/placeholderData/throwOnError here — restructure with conditional rendering or startTransition instead (see the Suspense guide).
2. status here only distinguishes success/error — loading is handled entirely by the surrounding <Suspense> boundary.

Connects To

• Suspense: the full conceptual guide for this hook's trade-offs and error-boundary reset pattern.
• useQuery: the base shape this hook is a constrained variant of.