Query Cancellation

By default, queries that unmount or become unused 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 just need to call cache.cancelQueries(key). If promise.cancel is available, React Query will cancel the request.

1 const [queryKey] = 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 
18 const cache = useQueryCache();
19 
20 return (
21   <button onClick={(e) => {
22     e.preventDefault();
23     cache.cancelQueries(queryKey);
24    }}>Cancel</button>
25 )