blog/mastering-mutations-in-react-query

[utterances-bot]

Mastering Mutations in React Query | TkDodo's blog

Learn all about the concept of performing side effects on the server with React Query.

https://tkdodo.eu/blog/mastering-mutations-in-react-query?utterances=22c272992acbd295c16b127dAie0B3x1NqhQorEKRGvFH71aM5MGXVEjl9WD5QZk2FjzX1Df%2FkFTH3OXs%2BinSDdYvbJn6fzf77VJgjGGyG9yk2I3qyKrT3CxpNink9ZEvoWXCAFbJKwKTpAZCv4%3D

[bustamantedev]

Another great post! You're on 🔥, congrats!

I have a question about some questions about this topic:

• Is it a bad practice to pass mutation results as props to children component and also as part of a context's value?

[TkDodo]

No, I don’t think it’s a bad practice. Personally, I try to keep the mutation as close to where it’s needed (e.g. the button that performs it) and I usually don’t need the result anywhere else, because the mutation influences associated queries, and I use those everywhere :)

[JaeYeopHan]

thanks for awesome post! i have a question @TkDodo,

i prefer use mutateAsync with unhandled promise rejection for handling unknown, unexpected error

1. intentionally throw error
2. capturing error in unhandled promise rejection
3. show toast message and capture exception stacktrace with sentry

so, my question is...

1. How about this error handling practice?
2. How to handle unexpceted error handling with mutate?

[TkDodo]

@JaeYeopHan For global error handling, I would set an onError event handler on the MutationCache. It will be executed once for every error that occurs for any mutation. I'm describing this here: https://tkdodo.eu/blog/react-query-error-handling#the-global-callbacks

[ChambreNoire]

Would there be any problem navigating to a different view within onError ? Say, to go to a /login page in the case of a 401 error...

[TkDodo]

that should be fine

[JaeYeopHan]

@TkDodo oh thanks! :)

onError event handler on the MutationCache

that's the part I missed.
may i ask you what is the difference between unhandled promise rejection handler and MutationCache onError handler?

[TkDodo]

@JaeYeopHan unhandled promise rejections occur when the browser sees a failed Promise without a .catch anywhere. If you use .mutate, react-query will catch it for you so that can't happen. The global onError callbacks are just additional functions that are invoked when an error occurs.

[arthurdenner]

Awesome post, thanks for sharing! Returning a Promise from onSuccess has solved some UI details in a current project I'm working on 🎉

[JanStevens]

@TkDodo Thanks for the awesome article, I guess I have been doing mutations all wrong!
A common pattern I use is having multiple custom hooks that internally call useMutation and handle the cache invalidation / optimistic updates. Typically a user goes through a multi step form and we need to update / create multiple resources.

I always used mutateAsync so I could await, get the result and then call the next mutation. How would you solve a typical case like that?

[TkDodo]

I always used mutateAsync so I could await, get the result and then call the next mutation. How would you solve a typical case like that?

Dependent mutations can basically be solved in 3 different ways. It's a pity I didn't get to include that in the article, I kinda forgot about it 😅 :

1. make multiple calls inside the mutateFn:

const mutate = useMutation((data) =>
  axios.post('/something', { data })
    .then((somethingResult) =>
        axios.put('/somethingElse', { somethingResult } )
  )
)
<button onClick={() => mutate('data') />

advantage would be one mutation with one loading state. disadvantage would be you can't easily trigger them separately if you'd need to.

2. with mutateAsync:

const mutate1 = useMutation((data) => axios.post('/something', { data }))
const mutate2 = useMutation(somethingResult) => axios.put('/somethingElse', { somethingResult })

<button onClick={async () => {
  try {
    const somethingResult = await mutate1.muteateAsync('data')
    const result = await mutate2.mutateAsync(somethingResult)
  } catch {}
}}/>

a bit boilerplate-y and you'd need to combine loading states very likely

3. like 2, but with mutate and callbacks:

const mutate1 = useMutation((data) => axios.post('/something', { data }))
const mutate2 = useMutation(somethingResult) => axios.put('/somethingElse', { somethingResult })

<button onClick={() => {
    mutate1.mutate('data', {
      onSuccess: mutate2.mutate
    })
}}/>

separated, but still quite concise. will get messy with more than 2 mutations, and the end-result would only be available in the onSuccess callback of the second mutation if you need it

[JanStevens]

Hi, thanks I figured it will be one of those 3, still torn on what should be used best. ATM we use option 2 (without the try / catch woopsie), but we also so a couple of issues with toasters flying in too early and page redirects to newly created resources not always working (cache is being updated but page is already redirecting)

The last option also seems a bit messy but I understand the reasoning. What I'm thinking now is having 3 independent useMutation hook wrappers and then wrap those in a component specific hook also using useMutation, not sure how that will pan out but going to try that. The benefit would be that I still can call the hooks independently but I can also call them in one go.

Thanks for the reply!

[hedaukartik]

how can I mock useIsMutating hook with msw or jest for fetching state of particular mutationKey?

[TkDodo]

@hedaukartik if you use msw, you'd just mock the network request for the given mutation and useIsMutating would just return the correct value, because the request is "in-flight" as far as react-query is concerned. That's the beauty of mocking on that level :)

[hedaukartik]

@TkDodo my use-case was to show loader in different component and not in the component where my useMutation is called. useIsMutating helped me in same.
While testing if loader is shown on different component..in my RTL test case of the component..i triggered useMutation wrapper hook using renderHook provided by @testing-library/react-hooks and with waitFor I was able to see loader in test as well.

In the docs, const isMutatingPosts = useIsMutating(['posts']) this is working for me on any mutation happening. Even if I add 'postsssss' or 'pooosts', it goes in fetching state. This worked for me- const isMutatingPosts = useIsMutating({ mutationKey: 'posts'}) if mutationKey is 'posts' in useMutation.

PS. MSW is smooth with react-query. Thanks for your amazing articles out there.

[woomiz]

Beautiful article, enjoyed all the way through including comments.

[RSchneider94]

Hey, many thanks for your awesome articles! They really helped me a lot to learn react-query more deeply! Unfortunately I'm kinda stuck here with a mutation and I can't figure out how to make this work, if some of you guys had already this scenario and could give some hints it would help me a lot.

So I have built my mutation:

export const useAddPeer = (
  portfolioId: PortfolioId,
): UseMutationResult<PortfolioWithPeers, unknown, PeerRequestBody, unknown> => {
  const queryClient = useQueryClient();

  return useMutation(
    (newPeer: PeerRequestBody) =>
      handleRequest<PortfolioResponse, AddPeersIntoPortfolioRequestBody>({
        url: `${API_PATH}/${portfolioId}/peers`,
        method: 'PUT',
        payload: {
          peers: [newPeer],
        },
      }),
    {
      onSuccess: () => queryClient.invalidateQueries('portfolio-overview'),
    },
  );
};

And here is how I call it:

const addPeer = useAddPeer(activePortfolio.id);

const handleAddPeer = (newPeer: PeerRequestBody) => () => addPeer.mutate(newPeer);

<Box
  onClick={handleAddPeer({
    tickerId: ticker.id,
    isFavorite: false,
  })}
> ... </Box>

and my PUT request works fine, but my mutation never happens (and I went into onSuccess with the debugger) but as far as I saw, I can just see one query key there, but not the one I'm trying to mutate 'portfolio-overview'.

And here is how my portfolio-overview query looks:

export const usePortfolioOverview = (
  portfolioId: PortfolioId,
): UseQueryResult<PortfolioOverviewResponse, Error> =>
  useQuery<PortfolioOverviewResponse, Error>(
    ['portfolio-overview', portfolioId],
    () =>
      handleRequest({
        url: `${API_PATH}/${portfolioId}/overview`,
        method: 'GET',
      }),
    {
      enabled: !!portfolioId,
    },
  );

basically the logic is -> I'm inside another component which I search for the "peers" and after clicking on it, it's added to the portfolio, which then maps all peers and display all of them in a list, and that's what I'm trying here, to mutate this list after adding a new peer to it.

[cmacdonnacha]

Great article @TkTodo.

This may be just preference but when creating a custom hook, is it better to return the mutation or only the parts you want to expose?

const useUpdateTodo = () => {
  const { mutate: updateTodo, isLoading, isError } = useMutation(...)

  return { updateTodo, isLoading, isError };
}

// in the component
const { updateTodo, isLoading, isError } = useUpdateTodo()

if (isLoading) {
  show loading component
}

updateTodo(
  { title: 'newTitle' },
  { onSuccess: () => history.push('/todos') }
)

I feel like it's a bit cleaner as you can use the function like updateTodo instead of mutate.updateTodo, but is less flexible.

[TkDodo]

i usually return everything

[cmacdonnacha]

Thanks. One more question on patterns. I've seen some examples using mutationFn and others using an inline function. Is there any reason to use one over the other?

const mutation = useMutation(() => axios.post('/someurl'));

vs

const mutation = useMutation({
  mutationFn: () => axios.post('/someurl')
});

[TkDodo]

the first notation is not possible anymore with v5, where the API was changed to only allow an object. The second version was possible in v4 as well, but in v5, it's the only allowed syntax.

[cmacdonnacha]

Gotcha. We're still on v3 so it sounds like we should always use mutationFn to make upgrading easier.

[lalosh]

Great writing 🎉

Just need to ask you about invalidation, you mentioned that:

However, only the ones that are currently active will be refetched. The rest will be marked as stale, which will cause them to be refetched the next time they are used.

What if I need to force an inactive query to be refetched because I don't want the user to wait for it when he reaches to that UI part that has the inactive observer, is this possible with react-query?

[TkDodo]

absolutely. You can either:

• pass refetchType: all as an option to invalidateQueries
• use refetchQueries instead of invalidateQueries, because it will always refetch all matching queries.

[thangnguyen22y]

Thanks for a great topic @TkDodo <3

May I ask you a question:
I'm using Tanstack React Query v5, with Mutation, can I change the component state directly in onSucess callback, or should I use useEffect() with isSuccess const from useMutation(...) to change state? Which one is the best practice?
As I known, we should not change state in onSuccess of useQuery(...), but not sure about Mutation.
(In my case, after save successfully, I want to call setState() to hide the current part)

[TkDodo]

it's fine for mutations

[dovranJorayev]

Thanks for a great topic @TkDodo <3

May I ask you a question: I'm using Tanstack React Query v5, with Mutation, can I change the component state directly in onSucess callback, or should I use useEffect() with isSuccess const from useMutation(...) to change state? Which one is the best practice? As I known, we should not change state in onSuccess of useQuery(...), but not sure about Mutation. (In my case, after save successfully, I want to call setState() to hide the current part)

I guess if there is an options to use it is good to not have logic in useEffect, because with react 18 in dev mode it is triggered twice, don't sure maybe it will be default behavior for production in future for some cases. So i think it is good to place the logic of side effects inside mutation's onSuccess/onError/onSettled handlers and do all you need there directly than doing it indirectly via useEffect.

useMutation({  
   queryFn: () => getCategories(),  
   onSuccess: () => {  
       handleClose(); 
   },  
   onError: () => {  
      toast.error('Ups');
  },  
}); 

[thangnguyen22y]

Yeb, with this way, our code looks very nice and concise. I really want to go with it.
Just a bit worry if any issues relating if we change state in onSuccess callback, by some people tell me that we shouldn't do it on this way (change state in onSuccess)

[dovranJorayev]

some people tell me that we shouldn't do it - this depend on context of use. I know that in general react-query force you not duplicate your state between "local state" and "server state". For this reason i guess in current major update there is not onSuccess/onError handlers in useQuery itself, but useMutation is different. useMutation should have onSuccess/onError, and there only correct place to perform side effects, if you using this hooks

[thangnguyen22y]

but useMutation is different. useMutation should have onSuccess/onError, and there only correct place to perform side effects, if you using this hooks => okay, I think you're correct. Thanks for the ideas!

[Aakash007-ai]

Hi @TkDodo,
I have encountered with a problem.
I successfully implemented React Query in React Native (to make offline first application).

There is a scenario where i am failing.

I open app and goes inside some screen then i turned on internet. At that point i want to resume mutation.

I am successfully in resuming mutation by default in all case.

Is there a way to resume mutation after app gets opened and then resuming mutation manually if it fails to resume (if initailly internet is not there but later we get internet connectivity)

Thanks

[TkDodo]

mutations should resume automatically when network connection is re-gained, if you've setup retries on mutations.

[ssrihari4102]

I'm a bit confused about whether one should use onError and/or onSuccess callbacks when using mutateAsync? Namely, I notice that the function signature for mutationAsync allows the use of these callbacks, but I don't see any examples (in this blog or elsewhere) where they are used in the mutateAsync options.

When I try using onSuccess and onError in useMutation and mutateAsync I notice the following:

• The onSuccess/onError for useMutation is called before that of mutateAsync
• If our mutationFn uses fetch and throws or Promise.rejects an error, the onError callbacks run
• If our mutationFn throws or Promise.rejects an error, the onError callbacks do not catch the error (the error propagates to the nearest error boundary)

Does this seem accurate?

[TkDodo]

Generally, I would only use mutateAsync over mutate if I also need access to the promise returned from it, for example, when I forward that promise to a toast library like react-hot-toast.

Have a read here: https://tkdodo.eu/blog/mastering-mutations-in-react-query#mutate-or-mutateasync

The onSuccess/onError for useMutation is called before that of mutateAsync

Yes, that's true and documented: https://tanstack.com/query/v5/docs/react/guides/mutations#mutation-side-effects

If our mutationFn uses fetch and throws or Promise.rejects an error, the onError callbacks run

Sure

If our mutationFn throws or Promise.rejects an error, the onError callbacks do not catch the error (the error propagates to the nearest error boundary)

only if you set throwOnError: true. Per default, we don't throw to error boundaries

[ssrihari4102]

Thanks. I am using mutateAsync since it seems that the mutation needs to be async for Formik to see it as a promise that should be resolved during submission and therefore modify isSubmitting properly.

Anyways, for the last point about errors not being thrown unless thrownOnError: true, isn't that only the case if we are using mutate? The blog mentions that mutate catches the errors, but since mutateAsync does not, this means we need to use a catch block even if we have an onError callback right?

[TkDodo]

Thanks. I am using mutateAsync since it seems that the mutation needs to be async for Formik to see it as a promise that should be resolved during submission and therefore modify isSubmitting properly.

yeah there's some overlap between formik and query here. If you want to use isSubmitting, you need to use mutateAsync and forward the promise. This is similar to the toast example I gave.

Of course, you could also just use isPending returned from useMutation that gives you pretty much the same info.

Anyways, for the last point about errors not being thrown unless thrownOnError: true, isn't that only the case if we are using mutate? The blog mentions that mutate catches the errors, but since mutateAsync does not, this means we need to use a catch block even if we have an onError callback right?

onError never catches or prevents errors. It's a callback that allows you to react to errors. "Do this when an error has happened".

You generally won't see react error boundaries when a promise from mutate / mutateAsync fails because error boundaries in react only catch errors that happen during rendering, but queries and mutations don't run during rendering - they run in effects or event handlers.

[ahmadchirp26]

Awesome post, I have question relating to dependent mutations. I know you have given an answer to that, but I would like to know what will you suggest about the following scenario.
I have to upload File type variables in mutation input, to a different service and get the url for that uploaded file from that service. After getting that url, I will be passing it into my mutation hook. Essentially I am transforming my input with File type variables to string type, and then a mutation call is made.

This pattern is followed throughout the entire application. I was hoping for some kind composition pattern, where I can wrap my mutation hooks, and adjust the mutation function somehow. I am not sure how to approach this. Kindly let me know your thoughts.

[TkDodo]

have one mutation that does multiple requests in the mutationFn

[vsrahul789]

Type '(formData: RegisterFormData) => Promise' has no properties in common with type 'UseMutationOptions<void, Error, RegisterFormData, unknown>'.

what should i do?

[TkDodo]

type your mutationFn

[ItsJustDaniel]

Hi @TkDodo, maybe I'm just stupid, but I have a question regarding optimistic updates. What if a user were to mutate very quickly and the time it took to fetch was too long for it to get cancelled on time. For example, in a a todo list if a user created two todos very fast, but the time it took to create the first todo was too long before the refetch got cancelled by creating the second todo. I don't know if that makes sense, so i've created a codesandbox to illustrate what I mean. I've used the code from the docs as an example. https://codesandbox.io/p/sandbox/friendly-river-3ty6zr?file=%2Fsrc%2Findex.js%3A62%2C33

[TkDodo]

what should I do in that sandbox to see the problem ?

[ItsJustDaniel]

In the sandbox, I've created an artificial delay of 5 seconds for the mutationFn to simulate the time it take to fetch something. the delay for the queryFn is 0. When you create multiple todos in a short time span, after the delay is over, it gets overwritten to its previous state then slowly reappears. this problem disappears when the delay of the queryFn matches the delay of the mutationFn and becomes worse the more farther apart it is. Which isn't completely unheard of because, presumably the nature of the queryFn would be a GET request and the nature of the mutation would be a POST request. This is a issue I've found in my own project and I had to do workarounds to fix it.

[TkDodo]

the trick is to stop invalidations from happening when you still have mutations going on:

 onSettled: () => {
+  if (queryClient.isMutating() === 1) {
     return queryClient.invalidateQueries()
+  }
 },

you can also pass filters to isMutating

[mapleveg]

Awesome blog :)

I have a question regarding mutation hook,

when you use async await refetchQueries in onSuccess lifecycle,
and then use that mutation onsuccess in a component, why is it that the data in the usequery is not "fresh"?
If I access the getQueryData in the onsuccess mutation it is "fresh".

[TkDodo]

I don't understand the question. Can you show a reproduction?

[MrEspiritu]

Hi, sorry for the bad explanation, here is an example that might show you better what I was trying to say.

const useUpdateTodo = () =>
  useMutation({
    mutationFn: updateTodo,
    onSuccess: async () => {
      await queryClient.refetchQueries({
        queryKey: ['list']
      })
    },
  })

// in the component
const {data} = useQuery({queryKey: ["list"]})

const updateTodo = useUpdateTodo()
updateTodo.mutate(
  { title: 'newTitle' },

  // on success waiting for the async await hook onSuccess to be done with the refetchingqueries
  { onSuccess: () => console.log(data) // The useQuery hook data is not up to date on this onSuccess lifecycle in the component}

I would believe it has something to do with the timing of rerendering, but I couldnt figure it out exactly how and when.
Thanks :)

[TkDodo]

I have a snarky tweet on that topic 😅

https://x.com/TkDodo/status/1644429549248081936

Basically it's just not how react and closures work. The click handler example in the next tweet should be obvious:

https://x.com/TkDodo/status/1644429552909967360

if you know why this doesn't work - it's the same with mutate.

[emmiep]

React Query waiting for promised returned by the callbacks is a great feature, but I'm wondering, how does this work with the callbacks on the mutate function? Will they fire only after the promises on the equivalent callbacks on useMutation have finished? For instance, I would want to make sure the invalidations have finished before running the code in my onSuccess callback on mutate().

[TkDodo]

Will they fire only after the promises on the equivalent callbacks on useMutation have finished?

yes.

[lopezignacio0091]

How do I stop mutateFn from continuing to run even if one of my requests fails?

[TkDodo]

mutations don't do that per default unless you have set the retry option

[Oner-T]

Hi
I would like to ask, If I need a mutate function in the UI, is there any way to guarantee it to fire before the component unmounts ? There are some cases I just need to use the mutates onSuccess or onError in the UI and that will make my job super easy, But as you mention in your post, it sometimes doesn't work most probably due to unmount of component before mutate onSucess fires.

[TkDodo]

if you use onSuccess on useMutation, it will always run. if you use onSuccess on mutate, it will only run if the component is still mounted when the mutation is finished.

[Oner-T]

hmm so there is no way to make component hold (not unmount), until the mutates' onSucess finishes, to make it guaranteed to work

[TkDodo]

no, and this is per design. the things that run in onSuccess of mutate should be things that should only run if the component is still mounted, like something that affects local state. For everything else - use the callbacks on useMutation.

[mrlectus]

So basically anything that affects the UI should be done in the mutate. if i want to set data to local storage i should do it in the useMutation?

[TkDodo]

yes

[Jamalahmad123]

Hi TkDodo,

I hope you're doing well. I really love this React Query series.

In v5, I'm facing a type issue in onSuccess. Here is what I'm seeing:

export const useAddPartner = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: addPartner,
    onSuccess(data) {
      queryClient.invalidateQueries({
        queryKey: partnerKeys.all,
      });
      sheetClose();
      toast.success(data?.message);
    },
  });
};

[Jamalahmad123]

sorry i hit the comment for the first one by mistake so here is the second part.
The data has type AxiosResponse<any, any>, and from the backend, I'm receiving the message property in data, which is working fine. However, TypeScript is complaining that message does not exist. Here is my default config options:

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        toast.error(`Something went wrong: ${error.message}`);
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      toast.error(`Something went wrong: ${error.message}`);
    },
  }),
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false,
      retry: false,
      // throwOnError: true,
    },
  },
});```

[TkDodo]

error.message should definitely exist because in v5, error is typed to Error (which has a message). Please try to show a typescript playground