Chapter 65: useMutation

Core Idea

The reference companion to the Mutations guide — precise signatures for the full callback lifecycle, mutate/mutateAsync's parallel shapes, and the scope/mutationKey options that control concurrency and default-inheritance.

Key Concepts

• mutationFn(variables, context): required unless a default is registered; context carries client (the QueryClient), mutationKey, and optional meta — distinct from the onMutate-returned rollback value.
• Callback signatures: onMutate(variables, context) (return value passed to onError/onSettled as onMutateResult); onSuccess(data, variables, onMutateResult, context); onError(err, variables, onMutateResult, context); onSettled(data, error, variables, onMutateResult, context) — all may return a Promise, which is awaited before the next callback runs.
• retry default differs from queries: 0 (no retries) by default for mutations, vs. 3 for queries — opt in explicitly.
• scope: { id }: defaults to a unique id per mutation instance (so all mutations run in parallel by default) — assign the same id to force mutations to run serially, queuing later ones with isPaused: true until earlier ones in that scope finish.
• mutationKey: lets a mutation inherit registered defaults from queryClient.setMutationDefaults(key, options) — separate concern from scope.
• meta: arbitrary metadata attached to the mutation cache entry, readable anywhere the mutation is visible (including MutationCache's global onError/onSuccess).
• mutate vs mutateAsync: mutate(variables, { onSuccess, onError, onSettled }) is fire-and-forget with call-site-specific callbacks (void return values, ignored); mutateAsync(variables, {...}) returns a Promise<TData> for await/try/catch composition. With multiple rapid calls, mutate's call-site onSuccess fires only for the latest call.
• Return fields beyond data/error/status: isPaused (true while paused for lack of network, per networkMode); reset() (clears back to initial state); failureCount/failureReason (retry bookkeeping, reset on success); submittedAt (timestamp of the triggering mutate/mutateAsync call, 0 by default); variables (the last variables passed in, undefined by default).

Reference Tables

Return field	Meaning
status	'idle' | 'pending' | 'error' | 'success'
isIdle/isPending/isSuccess/isError	Derived booleans
isPaused	Paused due to networkMode connectivity gating
mutate / mutateAsync	Fire-and-forget vs. Promise-returning trigger
reset()	Clears data/error back to idle
failureCount / failureReason	Retry bookkeeping (reset on success)
submittedAt	Timestamp of the last trigger call
variables	Variables from the last mutate/mutateAsync call

Key Takeaways

1. Remember the retry default flip vs. queries — mutations don't retry unless retry is set explicitly.
2. scope.id is the concurrency-control lever — same id serializes, distinct (default) ids parallelize.
3. When rapid consecutive mutate() calls are possible, only the latest call's own onSuccess/onError/onSettled fires — the hook-level callbacks (on useMutation itself) fire for every call regardless.

Connects To

• Mutations: the full conceptual guide behind this reference.
• Optimistic Updates: onMutate's rollback-context pattern, using the exact signature documented here.