What it does
Execute writes with mutate or mutateAsync. Lifecycle callbacks handle cache updates and rollback context.
Signature and parameters
MutationController<T, V> useMutation<T, V>(MutationOptions<T, V> options)
Live demo
Cached count: 0; fetching: false
Ownership and lifecycle
The app owns QueryClient and disposes it on logout or identity replacement. Hooks remove subscriptions and browser listeners on unmount. The final query unsubscribe cancels in-flight reads and schedules cache garbage collection. Mutation callbacks finish cache updates even after their component unmounts.
Server rendering
Hooks read prefetched data without starting I/O. Restore the dehydrated cache before the first client render. Use a request-scoped server client and explicit codecs; never put tokens into cached data. Mutations cannot execute in SSR hooks.
Common mistakes
Include every input in query keys. Do not mutate cached protobuf objects as form drafts. Read retries require explicit allowlisting and an error classifier; mutations never retry. Repository transports enforce the supplied deadline and register cancellation. Keep uncertain-save and version-conflict handling in the editor.
Related APIs
See the query guide for complete examples, defaults, prefetching, invalidation, optimistic updates and SSR hydration. QueryClientProvider, useQuery, useMutation, useQueryClient and useQueryLifecycle work together.