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.

Basic Mutations

Assuming the server implements a ping mutation, that returns "pong" string, here's an example of the most basic mutation:

1 const PingPong = () => {
2   const [mutate, { status, data, error }] = useMutation(pingMutation)
3 
4   const onPing = async () => {
5     try {
6       const data = await mutate()
7       console.log(data)
8       // { ping: 'pong' }
9     } catch {
10       // Uh oh, something went wrong
11     }
12   }
13   return <button onClick={onPing}>Ping</button>
14 }

Just as with useQuery you can also use booleans if you'd like:

1 const [
2   mutate,
3   { isIdle, isLoading, isError, isSuccess, data, error },
4 ] = useMutation(pingMutation)

Mutations without variables are not that useful, so let's add some variables to closer match reality.

Mutation Variables

To pass variables to your mutate function, call mutate with an object.

1 // Notice how the fetcher function receives an object containing
2 // all possible variables
3 const createTodo = ({ title }) => {
4   /* trigger an http request */
5 }
6 
7 const CreateTodo = () => {
8   const [title, setTitle] = useState('')
9   const [mutate] = useMutation(createTodo)
10 
11   const onCreateTodo = async e => {
12     // Prevent the form from refreshing the page
13     e.preventDefault()
14 
15     try {
16       await mutate({ title })
17       // Todo was successfully created
18     } catch (error) {
19       // Uh oh, something went wrong
20     }
21   }
22 
23   return (
24     <form onSubmit={onCreateTodo}>
25       <input
26         type="text"
27         value={title}
28         onChange={e => setTitle(e.target.value)}
29       />
30       <br />
31       <button type="submit">Create Todo</button>
32     </form>
33   )
34 }

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

Note that since version 1.1.0, the mutate function is no longer called synchronously so you cannot use it 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 }