Proposal: Add Debouncing to useQuery Hook Using the take Option

[Amr2]

Overview

The purpose of this proposal is to introduce a debounce mechanism for the useQuery hook in React Query. This would provide developers with the ability to control how frequently queries are triggered when inputs change (like search inputs or dynamic form filters).

The key idea is to add a new take option argument to useQuery, which determines whether to trigger the first, last, or every occurrence of the query within a specified debounce window.

---

Problem Statement

Currently, developers need to manually debounce queries when working with features like typeahead search, auto-complete, or real-time filters. This requires additional logic to be implemented by every developer, leading to repetitive, boilerplate code.

While React Query offers staleTime and cacheTime options, they do not address the issue of input-driven debounce logic. Most developers rely on libraries like lodash.debounce or create custom wrappers, which adds unnecessary complexity to projects.

---

Proposed Solution

We propose adding a take option to the useQuery configuration object, allowing developers to specify which event should "win" during a period of rapid consecutive calls.

New Option

const { data } = useQuery(queryKey, queryFn, {
  take: 'first' | 'last' | 'every', // New option (default: 'every')
  debounceTime: 300, // The debounce window (in milliseconds)
});

Option Definitions

Option	Description
take: 'first'	Triggers the first query call in the debounce window and ignores subsequent triggers.
take: 'last'	Triggers only the last query call in the debounce window. This is the most common form of debouncing.
take: 'every'	Allows every call to go through after a debounce delay. This acts more like a rate limiter.
debounceTime	The debounce window in milliseconds (default: 0).

Default behavior: If debounceTime is not provided, no debounce logic is applied. If take is not set, it defaults to 'every' to match the current behavior of useQuery.

---

Usage Examples

1️⃣ Take the "Last" Event (Classic Debounce)

This is the most typical use case for debouncing — only trigger the last query after the user stops typing for a specified delay.

const { data } = useQuery(['search', searchTerm], fetchSearchResults, {
  debounceTime: 300, 
  take: 'last', // Triggers only the last event after 300ms of inactivity
});

Use case: Autocomplete or search bars where the last input is the only one that matters.

---

2️⃣ Take the "First" Event

This approach is useful when you want to capture the first change and ignore everything else that happens within the debounce window.

const { data } = useQuery(['search', searchTerm], fetchSearchResults, {
  debounceTime: 300, 
  take: 'first', // Triggers only the first query within the 300ms debounce window
});

Use case: For situations like form submission, where you want to react immediately on the first action and ignore subsequent rapid actions.

---

3️⃣ Take "Every" Event (Rate Limiting)

This allows every event to be processed but only after a minimum debounce delay between queries.

const { data } = useQuery(['search', searchTerm], fetchSearchResults, {
  debounceTime: 300, 
  take: 'every', // Triggers every event after a 300ms delay
});

Use case: Ideal for scenarios where you want to send periodic updates to an API but still reduce the frequency of requests.

---

Proposed Implementation

Implementation Steps

1. Extend the useQuery Hook:
   • Add the take and debounceTime options to the hook's parameter configuration.
2. Internal Debounce Logic:
   • Use an internal debounce queue for each query key.
   • Track the first, last, and all trigger times.
3. Update the Query Execution Logic:
   • Apply logic to track which event to "take" (first, last, every) during the debounce period.
   • Use a mechanism similar to setTimeout or requestAnimationFrame to clear pending calls and trigger only the required one.

---

Alternatives Considered

1. Custom Wrapper Hooks: Developers can create custom hooks for debounce logic, but this leads to duplicated logic across projects.
2. Global Debounce Option: Add debounceTime to the global query client configuration. However, since debounce needs to be contextual, it makes more sense to keep it at the query level.
3. Leave It Out: This leaves developers relying on libraries like lodash.debounce, but this increases the learning curve for new users.

---

Benefits of This Proposal

• Improves DX: No need to create custom debounce logic in every project.
• Reduces Boilerplate: Avoids importing lodash.debounce and wrapping hooks.
• Enhanced Performance: Reduces unnecessary API requests.
• Backward Compatible: Defaults for take: 'every' and debounceTime: 0 ensure that existing projects won't break.

---

Drawbacks

• Complexity: Adds additional logic to the useQuery hook.
• Redundancy: Some may argue that staleTime and cacheTime already provide sufficient control, but they do not solve user-input-driven debounce issues.

---

Request for Feedback

We’d love feedback on the following aspects:

1. API Design: Does the proposed take: 'first' | 'last' | 'every' make sense, or would you suggest a different API?
2. Use Cases: Are there use cases we missed where this logic would be valuable?
3. Implementation Approach: Would you suggest changes to make it more performant or simpler?

---

We look forward to your thoughts and feedback!

[TkDodo]

Thanks for the detailed proposal - it warrants a detailed answer.

We’ve stated in the past that debouncing is one feature that will not make it into the Query API. I’ve talked about that in my recent talk at the React Advanced Conference “React Query API Design - Lessons Learned”:

• slides
• recording

The reason is manifold:

1. It adds complexity to the API

lodash.debounce has a lot of options - leading, trailing, maxWait, which I think is what users would expect us to support, too. Some users might want to have throttling instead - another option we’d need to support. All of this adds to bundle size as well - lodash.debounce is 1.14kb, which is roughly a 10% increase of our current size.

2. It’s easily doable in user-land

You’re saying it “adds unnecessary complexity to projects”, I would argue the opposite that it keeps unnecessary complexity out of React Query. It’s really just one additional line of code:

+  const debouncedSearchTerm = useDebounce(searchTerm, 500)

  const { data } = useQuery({
-   queryKey: ['search', searchTerm]
+   queryKey: ['search', debouncedSearchTerm]
    queryFn: fetchSearchResults,
  });

You can pick your favourite useDebounce hook that debounces a value, or write one yourself.

3. User-land can actually do it better!

With your proposal, the QueryKey would change with every keystroke, which creates a new cache entry with every keystroke, and then we would somehow debounce the call to the QueryFn. The user-land implementation debounces the queryKey, which means React Query will only know about the new cache entry after debouncing has finished. This is conceptually much closer to what you’d expect, as we wouldn’t create that many in-between entries.

4. Debouncing itself is likely a workaround

For example, for auto-complete, we likely just don’t want to send events until the user has “stopped” typing. Defining an arbitrary time for what “stopped” means seems ... arbitrary? In my example, it will also delay the fetch by 500ms after the user has stopped.

Since React 18, React offers the built-in useDeferredValue hook for low-prio updates that can be interrupted by high-prio updates (e.g. user input). With the user-land solution, you can do:

const deferredSearchTerm = React.useDeferredValue(searchTerm)

const { data } = useQuery({
  queryKey: ['search', deferredSearchTerm]
  queryFn: fetchSearchResults,
});

and kind of get the best of both worlds with a react built-in feature.