Invalidation from Mutations

Invalidating queries is only half the battle. Knowing when to invalidate them is the other half. Usually when a mutation in your app succeeds, it's VERY likely that there are related queries in your application that need to be invalidated and possibly refetched to account for the new changes from your mutation.

For example, assume we have a mutation to post a new todo:

 const [mutate] = useMutation(postTodo)

When a successful postTodo mutation happens, we likely want all todos queries to get invalidated and possibly refetched to show the new todo item. To do this, you can use useMutation's onSuccess options and the queryCache's invalidateQueries function:

1 import { useMutation, useQueryCache } from 'react-query'
2 
3 const queryCache = useQueryCache()
4 
5 // When this mutation succeeds, invalidate any queries with the `todos` or `reminders` query key
6 const [mutate] = useMutation(addTodo, {
7   onSuccess: () => {
8     queryCache.invalidateQueries('todos')
9     queryCache.invalidateQueries('reminders')
10   },
11 })

You can wire up your invalidations to happen using any of the following side-effect callbacks:

1 const [mutate] = useMutation(addTodo, {
2   onError: () => {
3     // An error happened!
4   },
5   onSuccess: () => {
6     // Boom baby!
7   },
8   onSettled: () => {
9     // Error or success... doesn't matter!
10   },
11 })

The promise returned by mutate() can be helpful as well for performing more granular control flow in your app, and if you prefer that that promise only resolves after the onSuccess or onSettled callbacks, you can return a promise in either!:

1 const [mutate] = useMutation(addTodo, {
2   onSuccess: async () => {
3     console.log("I'm first!")
4   }),
5   onSettled: async () => {
6     console.log("I'm second!")
7   })
8 })
9 
10 const run = async () => {
11   try {
12     await mutate(todo)
13     console.log("I'm third!")
14   } catch {}
15 }

You might find that you want to add additional side-effects to some of the useMutation lifecycle at the time of calling mutate. To do that, you can provide any of the same callback options to the mutate function after your mutation variable. Supported option overrides include:

• onSuccess - Will be fired after the useMutation-level onSuccess handler
• onError - Will be fired after the useMutation-level onError handler
• onSettled - Will be fired after the useMutation-level onSettled handler
• throwOnError

1 const [mutate] = useMutation(addTodo, {
2   onSuccess: (data, mutationVariables) => {
3     // I will fire first
4   },
5   onSettled: (data, error, mutationVariables) => {
6     // I will fire first
7   },
8   onError: (error, mutationVariables) => {
9     // I will fire first
10   },
11 })
12 
13 mutate(todo, {
14   onSuccess: (data, mutationVariables) => {
15     // I will fire second!
16   },
17   onSettled: (data, error, mutationVariables) => {
18     // I will fire second!
19   },
20   onError: (error, mutationVariables) => {
21     // I will fire second!
22   },
23   throwOnError: true,
24 })