Limitations of useSuspenseQuery hook

[krisko4]

Hello, I've recently played a little bit with react-query v5 and what caught my attention was the new useSuspenseQuery hook which looks promising. I've decided to use that solution to improve loaders in my app and reduce bundle size by combining API calls with code-splitting (I am using React without any framework).
So, to make things clear, my goal is to render a component which is lazy loaded and fetches some data from an API - for both of these operations I want to have a single loader displayed till they're finished.

The useSuspenseQuery hook seems to be a great solution for my problem and it works fine for simple cases. However, I've noticed some limitations:

• useSuspenseQuery cannot be enabled conditionally (as stated in the docs). This seems like a big limitation to me, as many fetch requests in my application are based on conditions (in most cases, my request needs some data received from another request in order to execute). As a workaround, i have to wrap those related requests in a promise and then pass that promise as a queryFn to useSuspenseQuery hook. It works, but it's not the most convenient way. I kind of feel like this solution has been designed for perfect-world situations where query parameters are always defined and request execution is not based on any conditions, which doesn't feel like a common case.
• refetchOnMount: 'always' option triggers an additional rerender when using useSuspenseQuery compared to useQuery. Maybe it should be mentioned in the docs as an important tip for people who decide to switch from useQuery to useSuspenseQuery?
• the Suspense section of the documentation seems a little bit lackluster. I believe that useSuspenseQuery hook can be a powerful improvement for many existing React projects (at least for me 😜 ). It provides a great opportunity to combine lazy loading with on-mount API calls and reduce the number of loaders if there are multiple API calls executed in a single view. However, the documentation doesn't emphasize those capabilities.
• in one of my projects, I am using useSuspenseQuery hook to render a lazy-loaded view which contains a table with pagination. I would like to display a loader while my page is being loaded (API call on component mount + bundle download). However, I don't want to display a loader again for the whole view after changing the page in my table - i'd rather display a smaller loader inside my table. With useQuery, I'd use a queryKey:

 const result = useQuery({
    queryKey: [currentPage] 
    queryFn: () => getData(currentPage)
  })

With useSuspenseQuery, this will trigger a fallback and a loader will be displayed for my entire page because I'm passing currentPage as a queryKey. As mentioned above, I don't want to trigger a fallback in such situation. This is my current workaround:

 const useFetch = (refetchKeys) => {
    const isFirstRender = useRef(true);

    const {data, isFetching, refetch} = useSuspenseQuery({
      queryKey: [currentPage] 
      queryFn: () => getData(currentPage)
  
    })

    useEffect(() => {
      // skipping refetch during first render as it is unnecessary
      if (isFirstRender.current) {
        isFirstRender.current = false;
        return;
      }
      if (queryKeys.length > 0) {
        refetch();
      }
    }, queryKeys);
    
  }

Now I can refetch my query without triggering a fallback. In order to display a loader inside my table, i am using isFetching property which seems to work for useSuspenseQuery. Do you guys think it's a valid approach? If so, maybe it could be a nice feature to consider adding as a prop?

 const {data, refetch} = useSuspenseQuery({
      queryKey: ['any key that triggers a fallback'],
      refetchKey: [currentPage] 
      queryFn: () => getData(currentPage)
    })

[TkDodo]

Thanks for the feedback 🙏. Let me try to address them one by one:

(in most cases, my request needs some data received from another request in order to execute)

Dependent Queries work out of the box with suspense, because the component suspends in between 😅 . The example from the docs simply becomes:

const { data: user } = useSuspenseQuery({
  queryKey: ['user', email],
  queryFn: getUserByEmail,
})

// no optional chaining needed because user is guaranteed to be defined here
const userId = user.id

// No need for enabled: !!userId
const {
  status,
  fetchStatus,
  data: projects,
} = useSuspenseQuery({
  queryKey: ['projects', userId],
  queryFn: getProjectsByUser,
})

This is actually one of the "pitfalls" with suspense - this creates a waterfall in requests, which is nice for dependent queries, but if you want multiple calls to queries to happen in parallel, you'd need useSuspenseQueries or split them up into separate components. On the other hand, with useQuery, they run in parallel per default, but you need enabled to make them dependent.

refetchOnMount: 'always' option triggers an additional rerender when using useSuspenseQuery compared to useQuery.

That's an architectural constraint because technically, suspense unmounts your component to render the fallback, then mounts it again when the promise resolves. This is expected imo if you set refetchOnMount: 'always', because a new mount happens. This is opt-in so don't set this flag to always if you don't want that. The recommendation is anyway to keep the flags as they are, and set a staleTime as you see fit. But sure, a callout in the docs won't hurt if you want to contribute that.

It provides a great opportunity to combine lazy loading with on-mount API calls and reduce the number of loaders if there are multiple API calls executed in a single view. However, the documentation doesn't emphasize those capabilities.

While this is nice (if used correctly, see the aforementioned waterfall when calling useSuspenseQuery multiple times in the same component), this is what suspense does and is probably better documented in the React docs. We're just trying to provide an integration with suspense. If you have a concrete suggestion, feel free to make a PR to the docs.

With useSuspenseQuery, this will trigger a fallback and a loader will be displayed for my entire page because I'm passing currentPage as a queryKey.

This is in the docs:

placeholderData also doesn't exist for this Query. To prevent the UI from being replaced by a fallback during an update, wrap your updates that change the QueryKey into startTransition.

You want useTransition or useDeferredValue, both feature provided by react. Again, this is just a brief sentence, because that's just how standard suspense works. If you want to learn about suspense in general, please consult the react docs - they are really great.

---

All in all, suspense is an architectural pattern shift and not just a flag that you turn on to get a "global loading spinner". It actually shines when used with a server side framework and streaming, not so much on the client only. This is also the reason why we've moved away from the suspense: boolean flag to a dedicated API that is purposefully more limited.

[krisko4]

Thank you for your reply, great lesson!

[krisko4]

Hello @TkDodo ,
thank you once again for your support. I'd like to ask you for one more advice. Following your tips, I've tried to use startTransition in order to prevent my UI from being replaced by a fallback during an update. It works well, however I'd like to find a way to track a loading state of my request in such case.
The real use case scenario is that I have a view which includes a table with pagination. On initial load, I'd like to display a loader for the entire view while the first page of my table is being loaded. Then, when switching the page, I'd like to display a loader inside my table. Unfortunately, I am unable to track the loading state of my request. I've noticed that with gcTime > 0 useSuspenseQuery sets isFetching property to true if the request is already stored in the cache. Otherwise, isFetching property is always false. I've prepared a simple codesandbox illustrating the problem:

https://codesandbox.io/p/sandbox/laughing-ishizaka-ykhj5q?file=%2Fsrc%2Findex.jsx%3A38%2C44

When switching the page for the first time, loader is not displayed. After changing from page 1 to page 2 and then back to page 1, the loader is visible.

I'm wondering if sticking with useSuspenseQuery is a good idea for my use case. I am aware that there are alternatives with useQuery such as keepPreviousData for pagination. However, I really like the idea of using Suspense instead of tracking loading state with isLoading property. What would you recommend? Thanks in advance!

[TkDodo]

however I'd like to find a way to track a loading state of my request in such case.

that's what useTransition does.

const [isPending, startTransition] = React.useTransition()

https://codesandbox.io/p/sandbox/objective-haslett-lfn855?file=%2Fsrc%2Findex.jsx%3A50%2C1

[krisko4]

Thanks, useTransition + gcTime: 0 seems to work well 👌🏻

[timsofteng]

@TkDodo What if userID in this example may be null or number and I would like only run second query if user is number?
Have no idea how to do it without using useQuery and loosing suspense.

[TkDodo]

• you can split it up into multiple components
• you can check for userID in the queryFn and return null instead of using enabled

[timsofteng]

As far as I can see queryFn cannot be null

    Type 'null' is not assignable to type 'QueryFunction<unknown, QueryKey, never> | undefined'.

[TkDodo]

it certainly can, show a typescript playground please

[timsofteng]

Is repo really necessary?
I just did this

  useSuspenseQuery({ queryFn: null, queryKey: ["test"] });

[TkDodo]

I didn't say pass null as the queryFn - the queryFn always needs to be a function. But it can return null...

[patricklafrance]

Hey @TkDodo thanks for all the great information. I am also struggling with the removal of the enabled property and I was wondering if you could provide guidance.

My use case is to load the initial data of my application:

• If a user initial request a public page, I want to load some global data like the application feature flags.

• If a user initial request is a protected page (a page behind a login), I also want to load protected global data like the user session.

So the way I was expecting to do that was with the enabled prop:

const { data: featureFlags } = useSuspenseQuery({ queryKey: A_KEY, queryFn: A_FN });

const isActiveRouteProtected = useIsRouteMatchProtected(....);

const { data: session } = useSuspenseQuery({ 
      queryKey: A_KEY,
      queryFn: A_FN, 
      enabled: isActiveRouteProtected   <---------------
});

In this example, my goal is to NOT make the session call if the route is not protected.

How would you do this? Should it be handled outside of React Query?

Thank you 🙏🏻

Patrick

[TkDodo]

one idea would be to not render the component that calls the query in those cases

[patricklafrance]

Thank you for your reply.

I am not sure if that would work for my use case. My goal is to render a single loading screen while the public data and protected data (if it's a protected route) are being fetch AND the remote modules of my federated applications are being loaded (which is a side effect happening outside of the React realm but integrated in React rendering flow through the usage of useSynxExternalStore).

Sorry my setup is very vague at the moment, I'll try to provide additional information tonight.

I was wondering though if my use case could be handled with useSupenseQueries ?

My thinking is that while the React Query hook cannot be dynamic, the array provided to useSupenseQueries could probably be dynamic? Always add the public data query to the array, if the route is protected, also add the protected data query to the array.

Thank you,

Patrick

[TkDodo]

useSuspenseQueries is a pretty smart idea that should work. The other option would to move the check into the queryFn and resolve with null if your conditions to make the request aren't met.

[patricklafrance]

Awesome I'll try both solutions!

On a side note, it's super impressive that you respond so quickly to questions of such a popular project! Thank you very much for all your contributions.

[alyyousuf7]

I used useSuspenseQueries to execute queries conditionally by creating something I call "null query":

/**
 * nullQueryOptions creates a query that returns null.
 * This is useful for cases where you want to execute a suspense query conditionally.
 *
 * @example
 * const [queryResult] = useSuspenseQueries({
 *   queries: [condition ? actualQueryOptions() : nullQueryOptions()],
 * });
 * if (isNullQueryResult(queryResult)) {
 *   // Handle the case where the query returned null
 * } else {
 *   // Handle the case where the query returned data
 * }
 */
export const nullQueryOptions = () =>
  queryOptions({
    queryKey: ['null'],
    queryFn: () => null,
  });

export const isNullQueryResult = (
  result: UseSuspenseQueryResult,
): result is UseSuspenseQueryResult<null> => result.data === null;

May be there's a better way to uniquely identify the "null query". Unfortunately, the query result doesn't return queryKey - otherwise I could have used that instead of null which could conflict with actual null data.

I defined isNullQueryResult as a reusable function in case someone wants to have a different mechanism later to identify "null query". As a bonus, it is more readable.

[bparsy-odin]

The limitation of not being able to disable a useSuspenseQuery hook is also giving me trouble in my case:
I use a tool to generate my api client with multiple hooks wrapping useQuery for each of my resources, it was very practical when I could pass suspense as an option to each of the resources I was trying to query, now I need to make every queries useSuspenseQuery to get that option, making it impossible to have the queries disabled when I need them disabled whether I use suspense or not.
I could duplicate all of my resources, one with suspense and one without but I think I will have to go back to v4, this is too inconvenient.

[TkDodo]

you can use the queryOptions API as an abstraction and then call useQueries(myOptions) or useSuspenseQueries(myOptions)

https://tkdodo.eu/blog/the-query-options-api