What is mutationKey?

[arcc1845]

The queryKey shares the cache among shared queries. What role does mutationKey play? It would be nice if it were documented.

[Lisba]

Hi, @arcc1845! The mutationKey role is to link a mutation with a default option already configured or to identify a mutation to share its state like loading, error, or data across components.

For instance:

1. Sharing default config:
   • You can set a default mutationFn for all the mutations with the key ['addProduct'] and then you can just call the useMutation hook with the mutation key without needing nothing else to be specified, this way, you avoid writing a lot of code and reuses it instead:
     queryClient.setMutationDefaults(['addProduct'], { mutationFn: addProductFunction })
const mutation = useMutation({ mutationKey: ['addProduct'] }).
   • Here you can find another example from the official doc.
   • Here you have a more practical example of a mutation key where you can share a more complex default config to persist mutations based on its mutation keys.
2. Sharing the mutation state across components:
   • You can just check the state of a mutation from any other component by its mutation key using the useMutationState
     const postsMutationState = useMutationState({ filters: { mutationKey: ['products'] } }).
   • Or using the useIsMutating hook to just check if a specific mutation (by its mutation key) is currently fetching const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] }).

I hope this helps to clarify a little bit more the role of the mutation keys 😉.

[KutnerUri]

@Lisba does it interact with query key at all?
maybe we can add this info to the official docs?

[seb-lean]

example 1 no longer available

[vv10110fake]

:(

[TkDodo]

https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetmutationdefaults