Mutations

Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, React Query exports a useMutation hook.

Here's an example of a mutation that adds a new todo the server:

1 function App() {
2   const [
3     mutate,
4     { isLoading, isError, isSuccess, data, error },
5   ] = useMutation(newTodo => axios.post('/todods', newTodo))
6 
7   return (
8     <div>
9       {isLoading ? (
10         'Adding todo...'
11       ) : (
12         <>
13           {isError ? <div>An error occurred: {error.message}</div> : null}
14 
15           {isError ? <div>Todo added!</div> : null}
16 
17           <button onClick={mutate({ id: new Date(), title: 'Do Laundry' })}>
18             Create Todo
19           </button>
20         </>
21       )}
22     </div>
23   )
24 }

A mutation can only be in one of the following states at any given moment:

• isIdle or `status === 'idle' - The mutation is currently idle or in a fresh/reset state
• isLoading or `status === 'loading' - The mutation is currently running
• isError or status === 'error' - The mutation encountered an error
• isSuccess or `status === 'success' - The mutation was successful and mutation data is available

Beyond those primary state, more information is available depending on the state the mutation:

• error - If the mutation is in an isError state, the error is available via the error property.
• data - If the mutation is in a success state, the data is available via the data property.

In the example above, you also saw that you can pass variables to your mutations function by calling the mutate function with a single variable or object.

Even with just variables, mutations aren't all that special, but when used with the onSuccess option, the Query Client's invalidateQueries method and the Query Client's setQueryData method, mutations become a very powerful tool.

IMPORTANT: The mutate function is an asynchronous function, which means you cannot use it directly in an event callback. If you need to access the event in onSubmit you need to wrap mutate in another function. This is due to React event pooling.

1 // This will not work
2 const CreateTodo = () => {
3   const [mutate] = useMutation(event => {
4     event.preventDefault()
5     return fetch('/api', new FormData(event.target))
6   })
7 
8   return <form onSubmit={mutate}>...</form>
9 }
10 
11 // This will work
12 const CreateTodo = () => {
13   const [mutate] = useMutation(formData => {
14     return fetch('/api', formData)
15   })
16   const onSubmit = event => {
17     event.preventDefault()
18     mutate(new FormData(event.target))
19   }
20 
21   return <form onSubmit={onSubmit}>...</form>
22 }

Resetting Mutation State

It's sometimes the case that you need to clear the error or data of a mutation request. To do this, you can use the reset function to handle this:

1 const CreateTodo = () => {
2   const [title, setTitle] = useState('')
3   const [mutate, { error, reset }] = useMutation(createTodo)
4 
5   const onCreateTodo = async e => {
6     e.preventDefault()
7     await mutate({ title })
8   }
9 
10   return (
11     <form onSubmit={onCreateTodo}>
12       {error && <h5 onClick={() => reset()}>{error}</h5>}
13       <input
14         type="text"
15         value={title}
16         onChange={e => setTitle(e.target.value)}
17       />
18       <br />
19       <button type="submit">Create Todo</button>
20     </form>
21   )
22 }

Mutation Side Effects

useMutation comes with some helper options that allow quick and easy side-effects at any stage during the mutation lifecycle. These come in handy for both invalidating and refetching queries after mutations and even optimistic updates

1 const [mutate] = useMutation(addTodo, {
2   onMutate: (variables) => {
3     // A mutation is about to happen!
4 
5     // Optionally return a rollbackVariable
6     return () => {
7       // do some rollback logic
8     }
9   }
10   onError: (error, variables, rollbackVariable) => {
11     // An error happened!
12     if (rollbackVariable) rollbackVariable()
13   },
14   onSuccess: (data, variables, rollbackVariable) => {
15     // Boom baby!
16   },
17   onSettled: (data, error, variables, rollbackVariable) => {
18     // Error or success... doesn't matter!
19   },
20 })

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 mutate(todo)

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 - Indicates that the mutate function should throw an error if one is encountered

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