Chapter 71: useSuspenseQueries

Core Idea

The Suspense variant of useQueries — the fix for the "multiple useSuspenseQuery calls in one component run serially" pitfall, since suspending components can't run more than one query's suspend/resume cycle side by side any other way.

Key Concepts

• Why it exists: useSuspenseQuery calls placed side by side in one component suspend on the first one before the others even start, turning what looks like parallel data-fetching into a serial waterfall — useSuspenseQueries({ queries: [...] }) fetches the whole array in parallel under Suspense instead.
• Shape: same { queries: [...] } array-of-options shape as useQueries.
• select typing limitation: identical to useQueries — an inline select on a query object can't infer from that object's own queryFn; use an explicit annotation or queryOptions().

Code Examples

const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
  queries: [
    { queryKey: ['users'], queryFn: fetchUsers },
    { queryKey: ['teams'], queryFn: fetchTeams },
    { queryKey: ['projects'], queryFn: fetchProjects },
  ],
})

• What it demonstrates: three queries fetched in true parallel under Suspense, replacing three separate useSuspenseQuery calls that would otherwise serialize.

Key Takeaways

1. The moment a second useSuspenseQuery (or more) appears in one component, switch all of them to one useSuspenseQueries call — this is the primary reason the hook exists.

Connects To

• Performance & Request Waterfalls: the serial-suspense pitfall this hook is the direct fix for.
• useQueries: the non-Suspense base shape, including the combine option and select typing caveat.