useSuspenseQuery

The useSuspenseQuery hook is a specialized version of useQuery designed for React Suspense. It always suspends while fetching and throws errors to error boundaries, providing a more streamlined type signature.

Import

import { useSuspenseQuery } from '@tanstack/react-query'

Signature

function useSuspenseQuery<
  TQueryFnData = unknown,
  TError = DefaultError,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
>(
  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
  queryClient?: QueryClient,
): UseSuspenseQueryResult<TData, TError>

Parameters

options

object

required

The query options object.

Show properties

queryKey

QueryKey

required

A unique key for the query. Must be an array.

queryKey: ['todos']
queryKey: ['todo', todoId]

queryFn

QueryFunction<TQueryFnData, TQueryKey>

required

The function that the query will use to request data. Cannot be skipToken.

queryFn: async ({ queryKey }) => {
  const response = await fetch(`/api/todos/${queryKey[1]}`)
  return response.json()
}

staleTime

number | 'static' | ((query: Query) => number | 'static')

default:"0"

The time in milliseconds after data is considered stale.

gcTime

number

default:"300000"

The time in milliseconds that unused/inactive cache data remains in memory.

refetchInterval

number | false | ((query: Query) => number | false)

default:"false"

If set to a number, the query will continuously refetch at this frequency.

refetchIntervalInBackground

boolean

default:"false"

If true, refetch will continue while the tab is in the background.

refetchOnWindowFocus

boolean | 'always' | ((query: Query) => boolean | 'always')

default:"true"

Refetch on window focus behavior.

refetchOnReconnect

boolean | 'always' | ((query: Query) => boolean | 'always')

default:"true"

Refetch on reconnect behavior.

refetchOnMount

boolean | 'always' | ((query: Query) => boolean | 'always')

default:"true"

Refetch on mount behavior.

retry

boolean | number | ((failureCount: number, error: TError) => boolean)

default:"3"

Retry configuration for failed queries.

retryDelay

number | ((failureCount: number, error: TError) => number)

Delay between retries in milliseconds.

select

(data: TQueryData) => TData

Transform or select part of the data.

select: data => data.items

networkMode

'online' | 'always' | 'offlineFirst'

default:"'online'"

Network mode configuration.

retryOnMount

boolean

default:"true"

If false, the query will not retry on mount if it contains an error.

notifyOnChangeProps

Array<keyof UseSuspenseQueryResult> | 'all'

Properties to track for re-rendering.

Returns

UseSuspenseQueryResult<TData, TError>

object

The query result object. Data is always defined (never undefined).

Show properties

data

TData

The last successfully resolved data for the query. Always defined (never undefined).

error

TError | null

The error object for the query. Always null when data is available.

status

'success'

Always 'success' because the query suspends on pending and throws on error.

fetchStatus

'fetching' | 'paused' | 'idle'

The fetch status of the query.

isPending

false

Always false because the query suspends during pending state.

isLoading

false

Always false because the query suspends during loading state.

isFetching

boolean

true if the query is currently fetching (background refetch).

isSuccess

true

Always true when the component renders.

isError

false

Always false because errors are thrown to error boundaries.

isRefetching

boolean

true if a background refetch is in progress.

isStale

boolean

true if the data is stale.

isRefetchError

boolean

true if the query failed during a background refetch.

dataUpdatedAt

number

Timestamp of when the query most recently returned success.

errorUpdatedAt

number

Timestamp of when the query most recently returned an error.

failureCount

number

The failure count for the query.

failureReason

TError | null

The failure reason for the query retry.

refetch

(options?: RefetchOptions) => Promise<UseSuspenseQueryResult>

Function to manually refetch the query.

Examples

Basic Usage

import { Suspense } from 'react'
import { useSuspenseQuery } from '@tanstack/react-query'

function Todo({ id }: { id: number }) {
  const { data } = useSuspenseQuery({
    queryKey: ['todo', id],
    queryFn: async () => {
      const response = await fetch(`/api/todos/${id}`)
      return response.json()
    },
  })

  // data is always defined, no need to check for undefined
  return <div>{data.title}</div>
}

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

With Error Boundary

import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
import { useSuspenseQuery } from '@tanstack/react-query'

function Todos() {
  const { data } = useSuspenseQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

function App() {
  return (
    <ErrorBoundary fallback={<div>Error loading todos</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <Todos />
      </Suspense>
    </ErrorBoundary>
  )
}

Multiple Suspense Queries

function TodoDetails({ id }: { id: number }) {
  const { data: todo } = useSuspenseQuery({
    queryKey: ['todo', id],
    queryFn: () => fetchTodo(id),
  })

  const { data: comments } = useSuspenseQuery({
    queryKey: ['comments', id],
    queryFn: () => fetchComments(id),
  })

  return (
    <div>
      <h1>{todo.title}</h1>
      <div>
        {comments.map(comment => (
          <p key={comment.id}>{comment.text}</p>
        ))}
      </div>
    </div>
  )
}

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

With Select

interface Todo {
  id: number
  title: string
  completed: boolean
}

function CompletedTodos() {
  const { data: completedTodos } = useSuspenseQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    select: (todos: Todo[]) => todos.filter(todo => todo.completed),
  })

  return (
    <ul>
      {completedTodos.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

Nested Suspense Boundaries

function UserProfile({ userId }: { userId: number }) {
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  })

  return (
    <div>
      <h1>{user.name}</h1>
      <Suspense fallback={<div>Loading posts...</div>}>
        <UserPosts userId={userId} />
      </Suspense>
    </div>
  )
}

function UserPosts({ userId }: { userId: number }) {
  const { data: posts } = useSuspenseQuery({
    queryKey: ['posts', userId],
    queryFn: () => fetchPosts(userId),
  })

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

function App() {
  return (
    <ErrorBoundary fallback={<div>Error</div>}>
      <Suspense fallback={<div>Loading user...</div>}>
        <UserProfile userId={1} />
      </Suspense>
    </ErrorBoundary>
  )
}

Notes

useSuspenseQuery requires React’s Suspense and Error Boundary to be set up in parent components.

The data property is always defined (never undefined) when the component renders, providing better type safety.

Errors are automatically thrown to the nearest error boundary, so you don’t need to handle error states manually.

The skipToken cannot be used with useSuspenseQuery. Use regular useQuery with enabled: false if you need conditional fetching.

Core

React API

Managers

Utilities

Import

Signature

Parameters

Returns

Examples

Basic Usage

With Error Boundary

Multiple Suspense Queries

With Select

Nested Suspense Boundaries

Notes

Build docs developers (and LLMs) love

Core

React API

Managers

Utilities

​Import

​Signature

​Parameters

​Returns

​Examples

​Basic Usage

​With Error Boundary

​Multiple Suspense Queries

​With Select

​Nested Suspense Boundaries

​Notes

Build docs developers (and LLMs) love

Import

Signature

Parameters

Returns

Examples

Basic Usage

With Error Boundary

Multiple Suspense Queries

With Select

Nested Suspense Boundaries

Notes