How best to prevent double button clicks and duplicate / parallel mutations

[mpvosseller]

Sometimes we find users are able to accidentally double click a button and kick off duplicate / parallel mutations.

We disable the button when mutation.isPending is true but that isn't set immediately on mutate so there is a short time window when it's possible to double click the button and kick off extra mutations.

Wondering if others experience this and if anyone has adopted a clean workaround? Or do folks live with the race condition?

Thanks!

Our buttons look like this:

<PrimaryActionButton
  type="submit"
  onClick={onSubmit}
  disabled={mutation.isPending}
  title="Submit"
/>

And our event handlers looks like this:

const onSubmit = handleSubmit(async (data) => {
  if (mutation.isPending) {
    return
  } 
  mutation.mutate({
    arg: 'value' 
  })
})

[TkDodo]

Does this differ from when you have a flag in local state that you set when the button is clicked? Because the component should re-render immediately with mutation.isPending just like if you were using local state.

[mpvosseller]

@TkDodo It is no different than using a regular react state flag: It's possible for multiple click events to get triggered before a re-render causes the state to get updated.

It can be solved with a useRef flag so it is always updated.

Was just wondering if others run into this issue and if so what (if anything) they do it fix or mitigate it. Maybe it's rare enough that the answer is nothing?

[sricks]

Running into this and typically you would use a ref here. Apollo useQuery does that automatically:

https://github.com/apollographql/apollo-client/blob/1f6decb950aa0a9759998f3f269b19f619950ba1/src/react/hooks/useMutation.ts#L290-L300

It's very easy to reproduce this and I'm surprised this doesn't have more attention, as unexpected duplicate mutations can be quite problematic and users often double click things.

May need to build a wrapper around react query to add this functionality.

[Wordllban]

I also received a bug report, specially from the Mac users, about this double-click problem. Ref is fine as workaround, but I believe this issue should have more attention. Since adding this ref does not differ from manual isLoading/isPending state handling

[Zelys-DFKH]

There are two separate things happening here.

TkDodo's point about disabled={mutation.isPending} is correct for a plain onClick. TanStack Query updates the store synchronously when mutate() fires, React re-renders, and the button becomes disabled before a second click can land. That works.

The if (mutation.isPending) return guard inside the handler is a different issue. It reads isPending from the closure captured at the last render, not from the live store. So after mutate() fires, the handler still sees false until the next re-render creates a new closure. For a plain click that window is tiny. With handleSubmit from react-hook-form it's much larger — async validation runs before your handler is called, and both clicks can complete validation before either calls mutate(). By then neither the button nor the guard has updated.

A ref doesn't have the stale closure problem. Every closure captures the same ref object, so reading mutatingRef.current always returns the live value regardless of when the closure was created:

const mutatingRef = useRef(false);

const onSubmit = handleSubmit(async (data) => {
  if (mutatingRef.current) return;
  mutatingRef.current = true;
  try {
    await mutation.mutateAsync({ arg: 'value' });
  } finally {
    mutatingRef.current = false;
  }
});

The if / set pair is synchronous, so even if two handleSubmit calls complete validation in parallel, only the first one through sets the flag. The second sees true and returns.

Keep disabled={mutation.isPending} on the button. It handles the common case and matters for accessibility. The ref covers the gap that async validation opens.

[sricks]

TanStack Query updates the store synchronously when mutate() fires, React re-renders, and the button becomes disabled before a second click can land. That works.

With all due respect, I don't believe this is true. The OP states they are using disabled={mutation.isPending} already and I've done the same, and double clicks can still happen. Which is why Apollo checks a ref value by default as linked above.

React rerenders are async and it's definitely possible to double click before a rerender happens. Even if the isPending value is updated synchronously, the disabled param won't be set in the DOM until rerender - which allows time for a second click.

So you still need to check the state value in the callback in a way that isn't dependent on the react render cycle. eg a ref, so that any double clicks are discarded.

Imo this should be a baseline behavior and it feels like a bug that this isn't handled by tanstack directly. Otherwise it creates a lot of complexity eg: If a mutation is pending and fires again:

• What does that do to the various loading/completion states? If the first mutation finishes does it stay as pending until the second one completes? Can you track both separately?
• How are onComplete callbacks handled? Are they called once or twice? With which version of state?

It seems silly that we'd all have to create our own refs to track this basic behavior - essentially necessitating the creation of custom wrappers. Which is probably a good idea for other reasons but this at least needs to be called out in the documentation.

[Zelys-DFKH]

Re-renders are async, but React 18 flushes synchronously after browser event handlers, so the button IS disabled before a normal second click is dispatched. The failure case is double-clicks within a single frame, where both events queue before any flush runs. The ref guard does not compensate for slow renders. It's the right primitive when you need guard semantics outside React's render cycle. Conflating the two weakens the case for a built-in solution.

[sricks]

I'm not super familiar with React's render internals, but unless I'm missing something, the end result is the same regardless of the cause.

The problem is that a user can click two times and have a mutation fire twice as a result, before the first mutation finishes. Which could result in eg double payments or other undesirable effects. But I might be missing a use case for this behavior.

It's the right primitive when you need guard semantics outside React's render cycle

Are there cases where users do not want double-click guards to apply outside of React's render cycle? In other words, they only want double-click guards within the limitations of React's update system, but for some reason they would want to allow double clicks that happen outside of React's control? Or allow double-mutations at all from any conceivable cause?

Conflating the two weakens the case for a built-in solution.

Not sure I understand as the real debate seems to be about whether duplicate mutations in progress are desirable or not. Someone who understands the internals well enough to disprove one will understand the other. And to me it seems clear that double clicks would not be desired by any user or developer working within normal ux paradigms and constraints. If someone wants to build an esoteric app that tests the user's ability to double click in a single frame I don't think they would use tanstack for that.

Of course this doesn't have to be implemented, I will simply create a wrapper for now and consider options in the future.

[Zelys-DFKH]

Fair, and that's exactly what makes a default hard.

"Add to cart" should allow multiple clicks:

// Click 3 times → 3 items added. That's correct behavior.
<button onClick={() => addToCartMutation.mutate({ productId, qty: 1 })}>
  Add to cart
</button>

A ref guard built into TanStack by default would silently drop clicks 2 and 3. Right for a payment form, wrong for a cart. TanStack can't know which you're building, so it can't safely make this the default.

Same reason the two failure modes are worth naming separately. "Stale closure" calls for a ref. "Re-render latency" calls for something else: a debounce, a queue, or just accepting that disabled covers enough. Lump them together and the docs give advice that works for one and silently fails the other.

Your wrapper is the right call, and the explicit naming is a feature:

const { mutate } = useSingleFireMutation(api.submitPayment);  // no duplicates
const { mutate } = useMutation(api.addToCart);                 // parallel fine

Agree the docs should address this directly. The gap between "disable the button with isPending" and "you also need a ref when async validation is involved" isn't obvious, and the consequences are severe enough that a community thread isn't the right place for it. If you open an issue, I'll write a first draft.