Mutations with useMutation and Cache Invalidation

In React Query terminology, a mutation is any operation that changes server data — POST, PUT, PATCH, or DELETE requests. While useQuery fetches and caches data, useMutation handles data modification with loading, error, and success states, plus powerful side-effect callbacks.

Separating queries (reads) from mutations (writes) is a key conceptual pattern. Mutations don't cache their results — they trigger side effects and then cause related queries to refetch fresh data.

useMutation takes a mutationFn — an async function that performs the write operation. It returns a mutate function (or mutateAsync for Promise-based usage) that you call when the user triggers the action.

Unlike useQuery, mutations don't run automatically. They wait for you to call mutate(variables). The hook provides isPending, isError, isSuccess, error, and data state from the mutation's response.

Call mutate(variables) to trigger the mutation. The variables argument is passed directly to your mutationFn. mutate is fire-and-forget — it doesn't return a Promise. Use the hook's onSuccess and onError callbacks to respond to the result.

Use mutateAsync(variables) instead when you need to await the result in an async function (e.g., to navigate after a successful post). Always wrap mutateAsync in try/catch — unhandled rejections will cause errors.

The onSuccess callback fires when the mutation completes successfully. It receives the mutation result data and the variables that were passed to mutate. Use onSuccess to invalidate related queries, show success feedback, reset forms, or navigate away.

You can define onSuccess at the hook level (for logic that always applies) and also pass it as a second argument to mutate(variables, { onSuccess }) for per-call customization.

Cache invalidation is the process of marking cached queries as stale after a mutation so they refetch fresh data. Use queryClient.invalidateQueries with a query key. Partial key matching is supported — invalidating ['posts'] invalidates all queries whose key starts with ['posts'], including ['posts', userId].

Invalidation triggers background refetches for all active (mounted) queries with matching keys. Components using those queries will show fresh data within one network round-trip.

Optimistic updates immediately update the UI before the server confirms the mutation. If the mutation succeeds, the speculative change is confirmed. If it fails, the UI rolls back to the previous state. This makes interactions feel instantaneous — no waiting for the server.

Implement optimistic updates in onMutate: save the current cache snapshot, update the cache immediately, then roll back in onError if needed. React Query provides queryClient.setQueryData to manually update the cache.

Use mutation status fields to provide appropriate UI feedback. isPending is true while the mutation is in flight — disable the submit button and show a spinner. isSuccess is true after completion — show a success message. isError is true if it failed — show the error message.

React Query resets mutation status automatically after a configurable gcTime period. To reset it manually (e.g., to allow the user to retry), call the reset() function returned by the hook.

Instead of invalidating and refetching, you can directly update the cache with the mutation response using queryClient.setQueryData. This is more efficient when the server returns the updated data in the mutation response — you can add it to the list without an extra network request.

This pattern — set cache from server response rather than invalidate — saves a network round-trip and is useful for lists where you want to append the new item immediately.

You can define global mutation callbacks in the QueryClient's defaultOptions.mutations for logging, error reporting, or token refresh that should apply to every mutation in the app. Local mutation options override global ones — both can coexist.

A common use case is a global onError callback that checks for 401 Unauthorized responses and triggers a logout or token refresh flow for every mutation, without repeating this logic in each individual useMutation call.

Mutations handle file uploads by accepting FormData as the variables. The mutationFn creates a FormData object and sends it with fetch using the multipart/form-data content type. React Query manages the loading and error state the same way as any other mutation.

For large file uploads, track progress using a custom fetch wrapper with XHR, storing progress in a separate state variable updated via the onUploadProgress pattern.

For workflows that require multiple sequential server operations (e.g., create order then process payment), chain mutations using mutateAsync in sequence. Each mutation can use the result of the previous one as its input. Wrap the chain in try/catch for error handling.

If intermediate steps fail, you may need to roll back earlier steps manually or trigger compensating transactions. Design your API for atomicity where possible to simplify client-side error recovery.

Test your understanding of React Native Mobile Development concepts from this lesson.

In this lesson you learned: useMutation handles write operations (POST/PUT/DELETE) with isPending, isError, and isSuccess state, onSuccess is the primary place to call queryClient.invalidateQueries to refresh related cached data, and optimistic updates via onMutate immediately update the cache with a rollback snapshot for if the server request fails. Next up we persist the React Query cache to AsyncStorage for offline-first behavior.