Feature request: staged / deferred query-string updates

[J3m5]

Hello,

I have a use case where in a modal where users adjust filters, the UI needs to respond instantly while the URL should update only after confirmation.
Because each setQueryState call writes straight to the address bar, the browser history fills with redundant states, cancelling edits is awkward, and users can copy links that don’t reflect the final selection.
A method to keep changes in memory and commit them in one transaction would be nice.

Thanks for maintaining nuqs.

[franky47]

You can do this by setting the throttleMs option to Infinity: this will decouple the URL update mechanism, and useQueryState(s) will essentially behave as useState (with sync between hooks that share a key).

When you're ready to update the URL, call the state updater function with the default value for throttleMs and it will do the update.

Edit: I forgot there was a test case for that:
https://github.com/47ng/nuqs/blob/next/packages/e2e/next/src/app/app/deferred/page.tsx

Screen.Recording.2025-06-17.at.23.29.18.mov