useTransition at the same level as useQueryState briefly reverts to the previous value — known limitation or bug?

[manuelj555]

Context

I isolated this behavior in a minimal repro after encountering it in a real application: filters where the user-selected value briefly jumps back to the previous value before finally settling on the new one.

I want to know whether this is a known limitation, unsupported usage, or a bug.

Reproduction

Sandbox: https://codesandbox.io/p/sandbox/7834g5

Important: this momentary revert only reproduces reliably without React StrictMode. With StrictMode enabled, I don't observe the committed value temporarily reverting.

Failing case: useTransition and useQueryState in the same component:

function App() {
  const [isPending, startTransition] = useTransition()

  const [count, setCount] = useQueryState(
    'count',
    parseAsInteger.withDefault(0),
  )

  useEffect(() => {
    console.log('rendered with count', count)
  }, [count])

  return (
    <button
      disabled={isPending}
      onClick={() => {
        startTransition(() => {
          setCount((c) => c + 1)
        })
      }}
    >
      {isPending ? '…' : '+ App transition'}
    </button>
  )
}

Observed log when running the linked sandbox (StrictMode disabled):

As shown above, after the click the committed value goes 267 → 266 → 267, coinciding with the period where isPending is true.

For comparison, if useTransition lives in an Actions-style child button and the parent component only owns useQueryState, I don't observe this revert. In my tests, React.startTransition (without isPending) in the same component also doesn't produce it.

What I think is happening (could be wrong)

1. setCount immediately updates nuqs' optimistic state.
2. The URL write is still queued, so location.search can briefly contain the previous value.
3. isPending triggers an urgent re-render of the same component that owns useQueryState.
4. Reconciliation re-reads the stale search params and overwrites the optimistic value.
5. Once the URL update is flushed, the state moves forward again.

This also fits an Actions-style button: if the pending UI is driven by useTransition in the component that owns the nuqs state, a filter can briefly flash the previous selection.

Why a discussion?

The documentation passes startTransition as a hook option rather than wrapping the setter directly. I'm not sure whether that implies the usage above is unsupported; if so, opening an issue might not be appropriate.

Questions

1. Is the new → old → new sequence a known limitation when useTransition lives alongside useQueryState?
2. Is wrapping a nuqs setter in useTransition (including via an Actions-style clickAction) considered unsupported?

Environment

• nuqs@2.9.2
• React 19
• Vite SPA + nuqs/adapters/react
• Reproduces without StrictMode

[manuelj555]

I also put together a second sandbox that adds Suspense + use + a promise cache on top of the same two buttons:

https://codesandbox.io/p/devbox/nuqs-use-transition-forked-jhl9t9?workspaceId=ws_PLaRjZcLzt7fJcDu3DxLXi

With that setup I’m seeing other inconsistencies beyond the count revert:

• + Action (transition in a child): Suspense fallback behavior is uneven — sometimes the fallback shows, sometimes it doesn’t (in my runs it often alternates click-to-click), even when the promise cache logs a MISS for a new count.
• With StrictMode on, the fallback tends to show much more consistently (which fits an urgent update path, but isn’t the transition UX I’d expect).
• If the promise lives in React state and is set in the same click handler as setCount, the fallback mostly goes away (previous UI + isPending), which suggests the weirdness is tied to deriving/use()-ing the promise from count across re-renders — not only to “Suspense being broken”.

Still the same underlying question: how useTransition / Actions are supposed to compose with nuqs updates, especially when the component that owns useQueryState re-renders while URL sync and Suspense are in flight.

(Same note as before: easier to judge without StrictMode.)

---

I’m also raising this with React’s async / Actions direction in mind. As that model spreads, component libraries will increasingly expose *Action callbacks (handlers meant to run inside useTransition for pending UI). In those cases the app author won’t manually wrap setQueryState — they’ll just pass an action that calls nuqs — and the same kind of temporary revert / Suspense inconsistency can show up. So this isn’t only about “did I use startTransition wrong”; it’s about whether nuqs stays safe when Actions become the default composition pattern.

[franky47]

I turned this into an issue in #1506.

[franky47]

As a general tip, you can await the result of the state updater function within startTransition to keep its pending status stable until the URL has finished updating.