Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, React Query exports a
Here's an example of a mutation that adds a new todo to the server:
A mutation can only be in one of the following states at any given moment:
status === 'idle'- The mutation is currently idle or in a fresh/reset state
status === 'loading'- The mutation is currently running
status === 'error'- The mutation encountered an error
status === 'success'- The mutation was successful and mutation data is available
Beyond those primary states, more information is available depending on the state of the mutation:
error- If the mutation is in an
errorstate, the error is available via the
data- If the mutation is in a
successstate, the data is available via the
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.
mutatefunction is an asynchronous function, which means you cannot use it directly in an event callback in React 16 and earlier. If you need to access the event in
onSubmityou need to wrap
mutatein another function. This is due to React event pooling.
It's sometimes the case that you need to clear the
data of a mutation request. To do this, you can use the
reset function to handle this:
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
When returning a promise in any of the callback functions it will first be awaited before the next callback is called:
You might find that you want to trigger additional callbacks than the ones defined on
useMutation when calling
mutate. This can be used to trigger component-specific side effects. To do that, you can provide any of the same callback options to the
mutate function after your mutation variable. Supported overrides include:
onSettled. Please keep in mind that those additional callbacks won't run if your component unmounts before the mutation finishes.
There is a slight difference in handling
onSettled callbacks when it comes to consecutive mutations. When passed to the
mutate function, they will be fired up only once and only if the component is still mounted. This is due to the fact that mutation observer is removed and resubscribed every time when the
mutate function is called. On the contrary,
useMutation handlers execute for each
Be aware that most likely,
useMutationis ansynchronous. In that case, the order in which mutations are fulfilled may differ from the order of
mutateAsync instead of
mutate to get a promise which will resolve on success or throw on an error. This can for example be used to compose side effects.
By default React Query will not retry a mutation on error, but it is possible with the
If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.
Mutations can be persisted to storage if needed and resumed at a later point. This can be done with the hydration functions:
For more information about mutations, have a look at #12: Mastering Mutations in React Query from the Community Resources.