How to push entries to browser history on button click only?

[wasimsandhu]

Hi, thanks so much for your work on nuqs! It was awesome to find exactly what I was looking for after manually syncing state with URL params myself.

I have a server component passing data to a client component. In the client component, I have an input field that accepts a number:

const [numParam, setNumParam] = useQueryState("num", parseAsInteger.withDefault(0));

New data is fetched with the new parameters on button click:

<Button
  disabled={isLoading}
  onClick={() => {
    startTransition(() => {
      router.push(`/myRoute?${searchParams}`);
    });
  }}
>
  Search
</Button>

I want to sync its state with the URL on the client side, but I only want to push entries to the browser history on button click, not on state change. How can I achieve this?

If I set history: "push" in the options, then the URL and state change on the client side, an entry is created in the browser history, but data is not fetched from the server until my button is clicked.

This creates a bunch of history entries where data for those parameters was never fetched. For example:

1. User enters 25, then clicks button. Data is fetched from server.
2. User enters 50, but doesn't click button. User then enters 75 and clicks button.
3. User clicks the back button, expecting data for num == 25 to be loaded, but instead the input is set to 50 and no data is loaded.

However, if I set history: "replace", this seems to override the default behavior of router.push -- it does not add entries to the browser history anymore.

I don't want to fetch data with throttling on each state change either. I can't seem to find anything in the docs that helps me achieve this. Am I approaching this problem wrong?

[franky47]

A combination of things to try:

• The shallow: false option in useQueryState to update the server whenever the num search param changes (that would take care of the back button giving you the right data)
• Using an uncontrolled number input, that reads its defaultValue from useQueryState, but URL updates only happen when clicking the button (the serializer in nuqs might help with generating a link from the input's internal value).

If you are on Next.js 14, be aware that there is a client cache that causes RSCs to be cached client-side, meaning if going back to a URL that previously fetched data, it won't invalidate/re-render server side unless this cache is cleared or disabled.
https://nextjs.org/docs/14/app/building-your-application/caching#router-cache

This was disabled in Next.js 15 IIRC.

[wasimsandhu]

Thank you for the helpful reply. The first option is fetching data on state changes, which is what I don't want. The second option may work, but having multiple uncontrolled inputs and a serializer is somewhat messy. And thank you for the note about the client cache, I was aware of this.

In the meantime, I will return to manually syncing state with the URL search parameters for my use case, since it doesn't seem to be covered by nuqs. Is this a use case you might support in the future?