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.

[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!

[elibroftw]

I recommend going one step further and ensuring that the throttle is only from true -> false and not from false -> true. When a user explicitly clicks a button, the loading UI will show immediately, but if the promise return immediately, the loading UI will show for a minimum amount of time.
In my case:

const accountLoading = useThrottledValue(accountLoadingRaw, accountLoadingRaw ? 400 : 0);

https://mantine.dev/hooks/use-throttled-value/

[elibroftw]

I'm turning my comment into an answer. A comment said that the API should not consider UI updates and I was convinced since the solution is much more controlled when using a throttle. The problem I have with iliasbhal's solution is that it also delays showing the loading UI. This is my solution which ensures that when we initiate a query/promise, the loading icon is shown asap, however if the query/promise has resolved, the loading state will be shown for at least a threshold. In my opinion, 200ms is a long enough time to communicate to the user that the application has done the work. I'm using Mantine as my component library, so I'm using their hooks. https://mantine.dev/hooks/use-throttled-value/. Otherwise you can use https://usehooks.com/usethrottle

const { loading: accountLoading, ... } = YOUR_OBJECT;
const accountLoadingDelayed = useThrottledValue(accountLoading, accountLoading ? 400 : 0);

[altugank]

I solved this by writing a small utility function that wraps the fetch call to enforce a minimum waiting time.

In my experience, just throttling the loading state isn’t enough - for example, with useMutation, the onSuccess or onError callbacks will still fire immediately, even if the loading state is throttled. By delaying the function itself, you ensure that both the UI state and lifecycle callbacks stay consistent.

export function delayedFunction<T extends (...args: any[]) => any>(
  fn: T,
  ms: number
): T {
  return (async (...args: Parameters<T>) => {
    const startTime = Date.now();

    const result = await fn(...args);
    const elapsedTime = Date.now() - startTime;
    const remainingTime = Math.max(0, ms - elapsedTime);

    if (remainingTime > 0) {
      await new Promise((resolve) => setTimeout(resolve, remainingTime));
    }

    return result;
  }) as T;
}

Usage

// Query example
const { data, isLoading, error } = useQuery({
  queryKey: ['exampleQuery'],
  queryFn: delayedFunction(getData, 1000),
});

// Mutation example
const { mutate, isPending } = useMutation({
  mutationFn: delayedFunction(saveData, 1000),
  onError: (error) => {
    console.error("Error saving data:", error);
  },
  onSuccess: (response) => {
    console.log("Data saved successfully", response);
  }
});

This way, you get consistent UX for both queries and mutations without having to repeat delay logic inside every function.

[BrendanC23]

What about using Promise.all() instead?

function sleep(ms: number) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

function delayFunction(promise: Promise<unknown>, ms: number) {
    return Promise.all([promise, sleep(ms)]);
}

const { data, isLoading, error } = useQuery({
  queryKey: ['exampleQuery'],
  queryFn: delayedFunction(getData(), 1000),
});

[altugank]

Oh great, that’s a better solution, I think. I was trying to preserve the types coming from TanStack Start’s server function, so here’s the typed version that works with it.

export function sleep(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

export function delayedFunction<T extends (...args: any[]) => any>(fn: T, ms: number) {
  return (async (...args: Parameters<T>) => {
    const [result] = await Promise.all([
      fn(...args), sleep(ms)
    ]);
    return result;
  }) as T;
}