useSuspenseQueries
The useSuspenseQueries hook is a Suspense-enabled version of useQueries. It suspends rendering until all queries have data and always returns data (never undefined).
Import
import { useSuspenseQueries } from '@tanstack/react-query'
Signature
function useSuspenseQueries<
T extends Array<any>,
TCombinedResult = SuspenseQueriesResults<T>,
>(
options: {
queries: readonly [...SuspenseQueriesOptions<T>]
combine?: (result: SuspenseQueriesResults<T>) => TCombinedResult
},
queryClient?: QueryClient,
): TCombinedResult
Type Parameters
Array type representing the queries configuration
TCombinedResult
type
default:"SuspenseQueriesResults<T>"
The type of the combined result when using the combine option
Parameters
Configuration object for the queriesqueries
readonly [...SuspenseQueriesOptions<T>]
required
An array of query options. Each query in the array accepts the same options as useSuspenseQuery.
combine
(result: SuspenseQueriesResults<T>) => TCombinedResult
Optional function to combine or select data from all queries. This function is called whenever any query updates.
Optional QueryClient instance to use. If not provided, the context client is used.
Returns
Returns an array of query results (one for each query), or the result of the combine function if provided. Each query result has the same shape as useSuspenseQuery results:
The data for the query. Always defined (never undefined) for suspense queries.
Always null for suspense queries (errors are thrown to error boundaries)
Always 'success' for suspense queries
Always true for suspense queries
Always false for suspense queries
Always false for suspense queries
Examples
Basic Usage
import { useSuspenseQueries } from '@tanstack/react-query'
function App() {
const results = useSuspenseQueries({
queries: [
{
queryKey: ['post', 1],
queryFn: () => fetchPost(1),
},
{
queryKey: ['post', 2],
queryFn: () => fetchPost(2),
},
],
})
// All data is guaranteed to be defined
const [post1, post2] = results
return (
<div>
<h1>{post1.data.title}</h1>
<h1>{post2.data.title}</h1>
</div>
)
}
With Combine Function
import { useSuspenseQueries } from '@tanstack/react-query'
function App() {
const combined = useSuspenseQueries({
queries: [
{
queryKey: ['post', 1],
queryFn: () => fetchPost(1),
},
{
queryKey: ['post', 2],
queryFn: () => fetchPost(2),
},
],
combine: (results) => {
return {
data: results.map((result) => result.data),
isPending: results.some((result) => result.isPending),
}
},
})
return (
<div>
{combined.data.map((post) => (
<h1 key={post.id}>{post.title}</h1>
))}
</div>
)
}
Dynamic Queries
import { useSuspenseQueries } from '@tanstack/react-query'
function Posts({ ids }: { ids: number[] }) {
const results = useSuspenseQueries({
queries: ids.map((id) => ({
queryKey: ['post', id],
queryFn: () => fetchPost(id),
})),
})
return (
<div>
{results.map((result) => (
<div key={result.data.id}>
<h2>{result.data.title}</h2>
<p>{result.data.body}</p>
</div>
))}
</div>
)
}
With Error Boundary and Suspense
import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
import { useSuspenseQueries } from '@tanstack/react-query'
function App() {
return (
<ErrorBoundary fallback={<div>Something went wrong</div>}>
<Suspense fallback={<div>Loading...</div>}>
<Posts />
</Suspense>
</ErrorBoundary>
)
}
function Posts() {
const results = useSuspenseQueries({
queries: [
{ queryKey: ['posts'], queryFn: fetchPosts },
{ queryKey: ['users'], queryFn: fetchUsers },
],
})
// All data is guaranteed to be defined
return <div>{/* render data */}</div>
}
Notes
skipToken cannot be used with any of the queries in useSuspenseQueries. If you need conditional fetching, use useQueries instead.- The component will suspend until all queries have loaded their initial data.
- If any query errors, the error is thrown to the nearest error boundary.
- All queries are run in parallel.
- The
enabled option is always set to true for all queries and cannot be disabled.