useSuspenseQuery

useSuspenseQuery is the Suspense-specific form of useQuery. It accepts query options and an optional QueryClient, suspends rendering while required data loads, and returns a result whose data is defined; loading and error handling are delegated to Suspense and error boundaries.

function useSuspenseQuery<TQueryFnData, TError, TData, TQueryKey>(options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseSuspenseQueryResult<TData, TError>;

UseSuspenseQueryResult<TData, TError>: the useQuery result shape with defined data, no isPlaceholderData, and status limited to success or error.

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

function Todos() {
  const { data } = useSuspenseQuery({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      if (!response.ok) throw new Error('Request failed')
      return response.json() as Promise<{ id: number; title: string }[]>
    },
  })

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

export function App() {
  return <Suspense fallback={<p>Loading…</p>}><Todos /></Suspense>
}

Fetches todos while React Suspense supplies the loading boundary; the hook returns defined data when Todos renders.