Form submission
Submitting a form that creates or updates server data.
TanStack · Hook
useMutation
useMutation configures and runs server-side writes such as creating, updating, or deleting data. It returns mutation state and commands for triggering, awaiting, or resetting the operation.
How it works
useMutation creates a mutation controller for server-side writes and other effects. Configure its mutation function and lifecycle callbacks, then call mutate with one variables value; the returned result exposes status, data, errors, reset, and promise-based mutateAsync behavior.
Syntax
function useMutation<TData, TError, TVariables, TOnMutateResult>(options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, queryClient?: QueryClient): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;Parameters
| Name | Type | Description |
|---|---|---|
options | UseMutationOptions<TData, TError, TVariables, TOnMutateResult> | The mutation configuration, including the mutation function and lifecycle options. |
queryClient | QueryClient | Optional custom client; otherwise the client from the nearest context is used. |
Returns
UseMutationResult<TData, TError, TVariables, TOnMutateResult>
Key points
- Use the hook for writes and other server-side effects, not ordinary read operations.
- The React API exposes useMutation as the hook used to configure and run a mutation.
- The options object contains the mutation function, callbacks, retry behavior, metadata, and other mutation configuration.
- Pass a QueryClient as the optional second argument when the mutation must use a client other than the nearest context client.
Example: Create and refresh a todo
import { useMutation, useQueryClient } from '@tanstack/react-query'
async function addTodo(title: string) {
const response = await fetch('/api/todos', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ title }),
})
if (!response.ok) throw new Error('Request failed')
return response.json() as Promise<{ id: string; title: string }>
}
export function AddTodo() {
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: addTodo,
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})
return <button onClick={() => mutation.mutate('Learn TanStack Query')}>
{mutation.isPending ? 'Adding…' : 'Add todo'}
</button>
}Defines a server-side create operation, starts it with mutate, and invalidates the todos query after success.
When to use it
Cache synchronization
Updating cached queries after a successful write.
Optimistic updates
Showing immediate UI changes while a write is in flight and rolling them back if it fails.
Interview questions
QWhen would you use useMutation instead of useQuery?
useMutation is intended for create, update, delete, and other server side-effects rather than fetching query data. Its options define the mutation function and lifecycle behavior, while the returned object exposes controls and state.
Follow-up: How should a successful write update displayed query data? Invalidate or refetch the affected queries from a lifecycle callback such as onSuccess.
QWhat is the difference between mutate and mutateAsync?
mutate starts the mutation and accepts one variables argument plus optional per-call callbacks. mutateAsync provides a promise that resolves on success and throws when the mutation fails.
Follow-up: When is mutate preferable? Use it for event-driven actions where the component can react through mutation state or callbacks without awaiting a promise.
QHow can mutation callbacks support optimistic updates?
onMutate runs before the mutation and can return a value passed to later callbacks. That value can carry information needed to undo an optimistic update when onError runs.
Follow-up: What should an optimistic-update implementation do after failure? Restore the previous cached value using the onMutate result, then reconcile or invalidate the relevant query.
Related
UseMutationOptionsUseMutationResultQueryClientmutatemutateAsyncMutationCacheuseQueryClient