useSuspenseQueries

React hook for running multiple queries in parallel with Suspense support

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

T · type

Array type representing the queries configuration

TCombinedResult · type · default: "SuspenseQueriesResults<T>"

The type of the combined result when using the combine option

Parameters

options · object · required

Configuration object for the queries

queries · 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.

queryClient · QueryClient

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:

data · TData · required

The data for the query. Always defined (never undefined) for suspense queries.

error · null

Always null for suspense queries (errors are thrown to error boundaries)

status · 'success'

Always 'success' for suspense queries

isSuccess · true

Always true for suspense queries

isPending · false

Always false for suspense queries

isError · false

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.