Mutations are used to send data updates to the server and apply the changes to the local cache. Mutations can also invalidate cached data and force re-fetches.
Mutation endpoints are defined by returning an object inside the
endpoints section of
createApi, and defining the fields using the
Mutation endpoints should define either a
query callback that constructs the URL (including any URL query params), or a
queryFn callback that may do arbitrary async logic and return a result. The
query callback may also return an object containing the URL, the HTTP method to use and a request body.
query callback needs additional data to generate the URL, it should written to take a single argument. If you need to pass in multiple parameters, pass them formatted as a single "options object".
Mutation endpoints may also modify the response contents before the result is cached, define "tags" to identify cache invalidation, and provide cache entry lifecycle callbacks to run additional logic as cache entries are added and removed.
onQueryStarted method can be used for optimistic updates
useMutation returns a tuple. The first item in the tuple is the "trigger" function and the second element contains an object with
useQuery hook, the
useMutation hook doesn't execute automatically. To run a mutation you have to call the trigger function returned as the first tuple value from the hook.
useMutation for the hook signature and additional details.
useMutation hook returns a tuple containing a "mutation trigger" function, as well as an object containing properties about the "mutation result".
The "mutation trigger" is a function that when called, will fire off the mutation request for that endpoint. Calling the "mutation trigger" returns a promise with an
unwrap property, which can be called to unwrap the mutation call and provide the raw response/error. This can be useful if you wish to determine whether the mutation succeeds/fails inline at the call-site.
The "mutation result" is an object containing properties such as the latest
data for the mutation request, as well as status booleans for the current request lifecycle state.
Below are some of the most frequently used properties on the "mutation result" object. Refer to
useMutation for an extensive list of all returned properties.
data- The returned result if present.
error- The error result if present.
isUninitialized- When true, indicates that the mutation has not been fired yet.
isLoading- When true, indicates that the mutation has been fired and is awaiting a response.
isSuccess- When true, indicates that the last mutation fired has data from a successful request.
isError- When true, indicates that the last mutation fired resulted in an error state.
With RTK Query, a mutation does contain a semantic distinction between 'loading' and 'fetching' in the way that a query does. For a mutation, subsequent calls are not assumed to be necessarily related, so a mutation is either 'loading' or 'not loading', with no concept of 're-fetching'.
This is a modified version of the complete example you can see at the bottom of the page to highlight the
updatePost mutation. In this scenario, a post is fetched with
useQuery, and then a
EditablePostName component is rendered that allows us to edit the name of the post.
In the real world, it's very common that a developer would want to resync their local data cache with the server after performing a mutation (aka "revalidation"). RTK Query takes a more centralized approach to this and requires you to configure the invalidation behavior in your API service definition. See Advanced Invalidation with abstract tag IDs for details on advanced invalidation handling with RTK Query.