Using imperative calls with a GET endpoint.. useQuery, useMutation, or don't use any of them...

[cafesanu]

Imperative Query in a Non-Linear Wizard Form

Hello all,

// First... our package.json

{
   ...
  "react": "18.3.1",
  ...
   "@tanstack/react-query": "^5.85.9",
   ...
}

We’re in a tricky spot with an imperative query. I came across this discussion by @TkDodo and this #1546, but our case is a little different.

We have a multi-step wizard form that’s not linear. It behaves more like a tree. The next form step depends on data from our backend.

Each step has a Next button, and based on some heavy logic (that cannot live in the frontend), the backend decides where the user should go.

Here’s a simplified pseudo-code example:

const AFormStepComponent = () => {
  const onSubmit = () => {
    // 1. Call the backend to figure out the next step
    // 2. Navigate to the step returned by the backend
  }

  return (
    <form onSubmit={handleSubmit}>
      ...
      <button type="submit">
        Next
      </button>
    </form>
  )
}

Since the backend isn’t mutating anything and only returns the next step, it’s exposed as a GET endpoint.

Naturally, our first instinct is to use useQuery for GET requests, but in this case, we’re unsure what’s best.

Here are the options we’re considering:

---

Option 1: useQuery

export const useNextQuery = ({ enabled, formStepInfo }) => {
  return useQuery({
    enabled,
    queryFn: () => api.getNext(formStepInfo), // internally uses fetch GET
    queryKey: formKeys(...),
  })
}

const AFormStepComponent = () => {
  const { formInfo } = useForm() // pseudo-code for simplicity
  const [enabled, setEnabled] = useState(false)

  const nextQuery = useNextQuery({ enabled, formInfo })

  if (nextQuery.isSuccess) {
    navigate(nextQuery.data.nextStep)
    return null
  }

  const onSubmit = (_formInfo) => {
    setEnabled(true)
  }

  return (
    <form onSubmit={handleSubmit}>
      ...
      <button type="submit">
        Next
      </button>
    </form>
  )
}

Pros

1. Stays consistent with TanStack Query and our conventions.

Cons

1. We don’t care about caching. It’s a one-time call.
2. It feels implicitly imperative; the logic isn’t clearly tied to onSubmit.

---

Option 2: useMutation

export const useNextMutation = () => {
  return useMutation({
    mutationFn: api.getNext,
  })
}

const AFormStepComponent = () => {
  const { formInfo } = useForm() // pseudo-code
  const nextMutation = useNextMutation()

  const onSubmit = (formInfo) => {
    nextMutation.mutate(formInfo)
  }

  return (
    <form onSubmit={handleSubmit}>
      ...
      <button type="submit">
        Next
      </button>
    </form>
  )
}

Pros

1. Explicitly imperative, which matches the flow.
2. Cleaner code. No workarounds for calling api.getNext.

Cons

1. Goes against TanStack Query + our convention of “GET = useQuery”.
2. The term mutation feels wrong here since nothing is being mutated.

Option 3: useMutation just as option 2 but change the names not to confuse developers

export const useNextGetImperative = () => {
  return useMutation({
    mutationFn: api.getNext,
  })
}

const AFormStepComponent = () => {
  const { formInfo } = useForm() // pseudo-code
  const nextGetImperative = useNextGetImperative()

  const onSubmit = (formInfo) => {
    nextGetImperative.mutate(formInfo) // still has the word mutate, which can confuse devs
  }

  return (
    <form onSubmit={handleSubmit}>
      ...
      <button type="submit">
        Next
      </button>
    </form>
  )
}

Pros

1. same as option 2 pros

Cons

1. same as option 2 cons
2. still has the word mutate when doing nextGetImperative.mutate, which can confuse devs

---

Option 4: Don’t Use TanStack Query

const AFormStepComponent = () => {
  const { formInfo } = useForm() // pseudo-code

  const onSubmit = async (formInfo) => {
    try {
      const { nextStep } = await api.getNext(formInfo)
      navigate(nextStep)
    } catch (err) {
      // handle error
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      ...
      <button type="submit">
        Next
      </button>
    </form>
  )
}

Pros

1. Simple.

Cons

1. Breaks consistency. We currently make all backend calls via TanStack Query.

---

The Question

Given that:

• This is an imperative, one-off GET request.
• We want clean, explicit code tied to the onSubmit flow.
• But we also want to stay consistent with TanStack Query.

👉 Which approach makes the most sense here?
👉 any other approach we are not thinking about or don't know about?

Thanks!!!

PS: We are aware of TanStack DB but, right now it's not possible for us to give it a try