Original fishing-dog mascot for jaspr_hooks jaspr_hooks

useMutation

Shared server state with query and mutation hooks.

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

Interactive useMutation 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.

See the query guide for complete examples, defaults, prefetching, invalidation, optimistic updates and SSR hydration. QueryClientProvider, useQuery, useMutation, useQueryClient and useQueryLifecycle work together.