Query Cancellation

By default, queries that become inactive before their promises are resolved are simply ignored instead of canceled. Why is this?

• For most applications, ignoring out-of-date queries is sufficient.
• Cancellation APIs may not be available for every query function.
• If cancellation APIs are available, they typically vary in implementation between utilities/libraries (eg. Fetch vs Axios vs XMLHttpRequest).

But don't worry! If your queries are high-bandwidth or potentially very expensive to download, React Query exposes a generic way to cancel query requests using a cancellation token or other related API. To integrate with this feature, attach a cancel function to the promise returned by your query that implements your request cancellation. When a query becomes out-of-date or inactive, this promise.cancel function will be called (if available):

Using axios

1 import { CancelToken } from 'axios'
2 
3 const query = useQuery('todos', () => {
4   // Create a new CancelToken source for this request
5   const source = CancelToken.source()
6 
7   const promise = axios.get('/todos', {
8     // Pass the source token to your request
9     cancelToken: source.token,
10   })
11 
12   // Cancel the request if React Query calls the `promise.cancel` method
13   promise.cancel = () => {
14     source.cancel('Query was cancelled by React Query')
15   }
16 
17   return promise
18 })

Using fetch

1 const query = useQuery('todos', () => {
2   // Create a new AbortController instance for this request
3   const controller = new AbortController()
4   // Get the abortController's signal
5   const signal = controller.signal
6 
7   const promise = fetch('/todos', {
8     method: 'get',
9     // Pass the signal to your request
10     signal,
11   })
12 
13   // Cancel the request if React Query calls the `promise.cancel` method
14   promise.cancel = () => controller.abort()
15 
16   return promise
17 })

Manual Cancellation

You might want to cancel a query manually. For example, if the request takes a long time to finish, you can allow the user to click a cancel button to stop the request. To do this, you need to set the key argument of useQuery to empty string and set the enabled option to false. If promise.cancel is available, React Query will cancel the request.

1 const [queryKey, setQueryKey] = useState('todos')
2 
3 const query = useQuery(queryKey, () => {
4   const controller = new AbortController()
5   const signal = controller.signal
6 
7   const promise = fetch('/todos', {
8     method: 'get',
9     signal,
10   })
11 
12   // Cancel the request if React Query calls the `promise.cancel` method
13   promise.cancel = () => controller.abort()
14 
15   return promise
16 }, {
17   enabled: queryKey.length > 0
18 })
19 
20 return (
21   <button onClick={(e) => {
22     e.preventDefault();
23     setQueryKey("");
24    }}>Cancel</button>
25 )