How to use Tanstack Form in conjunction with Tanstack Query mutation for proper form.state.isSubmitSuccessful?

[moebiuscorzer]

Context

I am using Tanstack Form in conjunction with Tanstack Query (and Tanstack Router). I do not manage to get the form isSubmitSuccessful to be false while not having an uncaught Promise at the same time, using mutate vs mutateAsync.

TL;DR

Issue:

• When using Tanstack Query mutation mutate as the form onSubmit function means the form is always considered as submitted successfully (form.state.isSubmitSuccessful) even if the mutate function failed (which is expected considering mutate is always resolved).
• When using Tanstack Query mutation mutateAsync as the form onSubmit function means the form is properly considered as submitted unsuccessfully when the mutateAsync function throws, but then there is an uncaught promise.

It is unclear what should be the idiomatic way to:

• Use Tanstack Query's mutations as the form onSubmit function
• Failure of the mutation function should mean the form.state.isSubmitSuccessful should be false
• Failure of the mutation function should not trigger an uncaught Promise.

I can do form.handleSubmit(/*...*/).catch((_noop) => {}) but that looks like a weird way to integrate the two libraries.

Question

Mutation

Let us say I have a mutation called action = useMutation(/*...*/). If I use action.mutate as the form submission function, I would expect the failed submission to set the form.state.isSubmitsuccessful to false but this is not the case. After all, since action.mutate is always a resolved Promise, that makes sense.

When I use action.mutateAsync, then the form state is as expected. However, the code is not correct because I then have an "Uncaught promise" showing up in the console.

Key question: what is the idiomatic way to ensure the form.isSubmitSuccessful is false when the action is failed? Should I use the onError callback to update the form state? How so?

When I look at the test code here´, it seems that form.state.isSubmitSuccessful´ should be false when the form.handleSubmit` throws.

mutate vs mutateAsync

I do understand that action.mutate does not return a failed promise since it is awaited and the error is caught without side-effect (as explained in TkDodo's blog).

But if I use mutateAsync, there is an uncaught Promise.

Solution

In the below, using:

form.handleSubmit(/*...*/).catch((_noop) => {})

Will achieve what is expected: form state is correctly "failed" but that looks like a weird way to integrate both libraries together.

Code

Here is my code:

import { useForm } from "@tanstack/react-form";
import { useMutation } from "@tanstack/react-query";
import { createFileRoute } from "@tanstack/react-router";
import { toast } from "sonner"; /* Not strictly necessary, just helps visually */

export const Route = createFileRoute("/_public/test")({
  component: RouteComponent,
});

function RouteComponent() {
  const action = useMutation({
    mutationFn: async (data: "fail" | "success") => {
      if (data === "fail") {
        throw new Error("Mutation failed");
      }

      return await Promise.resolve("Mutation succeeded");
    },
  });

  const defaultMeta = {
    submitAction: "success" as "fail" | "success",
  };
  const form = useForm({
    defaultState: {
      isSubmitSuccessful: false,
      isFormValid: true,
      isValid: true,
    },
    onSubmitMeta: defaultMeta,
    /* Switching this to mutate does not cause an uncaught promise but
       it means the form is always considered as submitted successfully
    */
    onSubmit: async ({ meta }) =>
      await action.mutateAsync(meta.submitAction, { 
        onError: () => {
          toast.error("Form submission failed");
        },
        onSuccess: () => {
          toast.success("Form submission succeeded");
        },
      }),
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
      className="flex flex-col gap-10"
    >
      <form.Subscribe
        selector={(state) => {
          return {
            isSubmitSuccessful: state.isSubmitSuccessful,
            submitted: state.submissionAttempts > 0,
          };
        }}
      >
        {({ isSubmitSuccessful, submitted }) => (
          <span className="bg-blue-500 text-center text-white">
            {!submitted
              ? "Not submitted"
              : isSubmitSuccessful
                ? "Submitted successfully"
                : "Submission failed"}
          </span>
        )}
      </form.Subscribe>
      <div className="flex flex-row gap-10">
        <form.Subscribe
          selector={(state) => {
            return { isSubmitSuccessful: state.isSubmitSuccessful };
          }}
        >
          {({ isSubmitSuccessful }) => (
            <button
              className="bg-green-500 text-white disabled:bg-gray-400"
              type="submit"
              onClick={() => {
                toast.info("Submitting success action...");
                form.handleSubmit({
                  submitAction: "success",
                });
              }}
              disabled={isSubmitSuccessful}
            >
              Success
            </button>
          )}
        </form.Subscribe>
        <form.Subscribe
          selector={(state) => {
            return { isSubmitSuccessful: state.isSubmitSuccessful };
          }}
        >
          {({ isSubmitSuccessful }) => (
            <button
              className="bg-red-500 text-white disabled:bg-gray-400"
              type="submit"
              onClick={() => {
                toast.info("Submitting fail action...");
                form.handleSubmit({
                  submitAction: "fail",
                });
              }}
              disabled={isSubmitSuccessful}
            >
              Fail
            </button>
          )}
        </form.Subscribe>
      </div>
      <button
        type="reset"
        className="bg-blue-500 text-white"
        onClick={(e) => {
          e.preventDefault();
          e.stopPropagation();
          form.reset();
        }}
      >
        Reset
      </button>
    </form>
  );
}

Versions

Tanstack React Form 1.23.5
Tanstack React Query 5.66.5
Tanstack Router 1.114.3
React 19.0.0
vite 6.1.0