Suspense

NOTE: Suspense mode for React Query is experimental, same as Suspense for data fetching itself. These APIs WILL change and should not be used in production unless you lock both your React and React Query versions to patch-level versions that are compatible with each other.

React Query can also be used with React's new Suspense for Data Fetching API's. To enable this mode, you can set either the global or query level config's suspense option to true.

Global configuration:

1 // Configure for all queries
2 import { ReactQueryConfigProvider } from 'react-query'
3 
4 const queryConfig = {
5   shared: {
6     suspense: true,
7   },
8 }
9 
10 function App() {
11   return (
12     <ReactQueryConfigProvider config={queryConfig}>
13       ...
14     </ReactQueryConfigProvider>
15   )
16 }

Query configuration:

1 import { useQuery } from 'react-query'
2 
3 // Enable for an individual query
4 useQuery(queryKey, queryFn, { suspense: true })

When using suspense mode, status states and error objects are not needed and are then replaced by usage of the React.Suspense component (including the use of the fallback prop and React error boundaries for catching errors). Please read the Resetting Error Boundaries and look at the Suspense Example for more information on how to set up suspense mode.

In addition to queries behaving differently in suspense mode, mutations also behave a bit differently. By default, instead of supplying the error variable when a mutation fails, it will be thrown during the next render of the component it's used in and propagate to the nearest error boundary, similar to query errors. If you wish to disable this, you can set the useErrorBoundary option to false. If you wish that errors are not thrown at all, you can set the throwOnError option to false as well!

Resetting Error Boundaries

Whether you are using suspense or useErrorBoundaries in your queries, you will need to know how to use the queryCache.resetErrorBoundaries function to let queries know that you want them to try again when you render them again.

How you trigger this function is up to you, but the most common use case is to do it in something like react-error-boundary's onReset callback:

1 import { queryCache } from "react-query";
2 import { ErrorBoundary } from "react-error-boundary";
3 
4 <ErrorBoundary
5   onReset={() => queryCache.resetErrorBoundaries()}
6   fallbackRender={({ error, resetErrorBoundary }) => (
7     <div>
8       There was an error!
9       <Button onClick={() => resetErrorBoundary()}>Try again</Button>
10     </div>
11   )}
12 >

Fetch-on-render vs Render-as-you-fetch

Out of the box, React Query in suspense mode works really well as a Fetch-on-render solution with no additional configuration. This means that when your components attempt to mount, they will trigger query fetching and suspend, but only once you have imported them and mounted them. If you want to take it to the next level and implement a Render-as-you-fetch model, we recommend implementing Prefetching on routing callbacks and/or user interactions events to start loading queries before they are mounted and hopefully even before you start importing or mounting their parent components.