Proposal: Minimum Loading Duration Option

[an2n]

Hi everyone,

I want to ensure a minimum loading time for API requests to:

• Show a loader even for fast responses, indicating that data is being retrieved.
• Provide a consistent user experience regarding wait times for content to appear.

Current Workarounds
Existing solutions usually involve custom modifications to the query function to artificially add a delay using setTimeout or delay operators. These workarounds require repetitive code within each query.

Example usage:

useQuery('myQuery', async () => {
  const startTime = Date.now();
  const response = await axios.get('/api/data');
  const endTime = Date.now();
  const delay = 1000 - (endTime - startTime);
  if (delay > 0) {
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  return response.data;
});

Previous Discussions
This feature request, regarding its use with the useMutation hook, has been mentioned before but without a solution:
Is it possible to have a minimum loading time for useMutation hook? #5428

Proposed Solution
Add an optional minLoadingDuration parameter to query options, working as follows:

• When a query initiates, record the start timestamp.
• After a response is received, check how long the query took in total.
• If the elapsed time is shorter than the minLoadingDuration, use setTimeout to wait for the remaining time before resolving the query promise.

Example usage

useQuery('myQuery', () => axios.get('/api/data').data, {
 minLoadingDuration: 1000 // Delay response for at least 1 second
}); 

Let me know if you'd like this proposal, want me to refine this further or help with a draft implementation.

[moaazassali]

Why not use a wrapper over axios and add the timeout there. That's what I do in my projects at least. I use fetch and since my API has a specific structure (like always using problem details for non-2XX responses, see RFC 7807), I have a wrapper over fetch to handle all http response errors and client side errors like network issues in a unified way. In that wrapper I also include a custom delay.

[an2n]

While interceptors (read wrapper) are useful, they aren't the right place for granular control over loading times, especially considering background fetches. Also, if I moved the delay to interceptors or just to the service itself, it would limit reusability across different queries, as I wouldn't be able to easily customise the delay duration.

Your proposal makes sense, but I value having control per query which this proposal promotes.

[an2n]

You're right that customisation is possible with a parameter, but using a minLoadingDuration option directly within queries offers a cleaner approach. This aligns well with the library's core focus on simplifying data fetching by ensuring loading state logic remains closely tied to the query.

[TkDodo]

sorry, I disagree here. Every option increases the api surface, and we already have 20+ options. This is a feature that isn't requested a lot - it's basically about "slowing down" things, and you can implement this either on the api layer or on the component layer. React query isn't about data fetching - it's about managing async state. It would be weird to ask a state manager to not give you data for a specific amount of time even though that data is already available ...

[an2n]

I respect your concerns, and I guess I will put this on the api layer instead.

[iliasbhal]

@an2n I suggest to NOT do it on the API layer. but to create a hook that will do that for you. My reasoning is that it's a cosmetic feature, therfore it shouldn't impact the API or any other thing expect the rendring aspect.

On my end, to avoid a flashing loading indicator, I ended up using a hook for that.
You can find it here: https://usehooks.com/usethrottle

	const { isLoading: isLoadingOG, ...rest } = useQuery(/* .... */)
	const isLoading = useThrottle(isLoadingOG, 500); // <---- like so.

[an2n]

That sounds like a great approach @iliasbhal, thanks for sharing!