Feature Idea: Load & save params to localStorage as an alternative default on page load

[tylersayshi]

So we have a route /some-page where we save lots of state in the query params. We want to be able to essentially restore the past session when someone navigates away, potentially even closes the site entirely, then returns to the original page later. To do this, we load query params through local storage.

Here is an example of someone on reddit asking for help with the same thing: https://www.reddit.com/r/nextjs/comments/1cz4j87/help_with_storing_query_params_in_local_storage/

This should be fairly easy to work into using nuqs with the withDefault method... that being said, I think it still might be useful to give examples in the docs or some built in support for this in nuqs.

Happy to help out with a PR depending on what you think here :)

[franky47]

A thing that's been on the Roadmap for a while is supporting functions for the default value.

This could help with this use-case, though it raises the question of when the function should run:

• Once at initialisation, and never again, like a function argument to React.useState
• Every time the default value is actually needed (eg: when the query is cleared or contains an invalid value that the parser cannot resolve)
• On every render (could be a performance pit)

[tylersayshi]

Every render seems unnecessary and easy to ignore given the performance considerations mentioned.

I can imagine once at initialization and also whenever the default is needed as both valid uses. I wouldn't have strong opinions between which is chosen, but would only really need to be able to handle the default at initialization.

Both could even be an option if there was an api to toggle between the behaviors somehow ¯_(ツ)_/¯

[tylersayshi]

The more I think about it, the more I think once at initialization might actually just be the most straightforward solution and all that is needed here.

I can imagine a scenario where we default some filters on a page (from localStorage in last session) - the user then hits "clear filters" which sets the query state to undefined and then hits the fallback in localStorage.

Now this could be corrected by handling empty states more appropriately, but it feels like too easy of a pitfall to have, for not a very strong use case in return. Unless of course you have other examples where partial fallback to localStorage is really helpful, and then the ability to choose behavior makes sense again.

[franky47]

One solution to differentiate the two scenarios of when to run the default function could be to have an argument passed to know in what context the function is being run. We could pass the current query string value as well (unparsed, I guess, in case the parser fails to produce a valid value which is one of the uses of the default value):

parseAsInteger.withDefault((query: string | null, context: 'init' | 'naming tbc') => {
  if (context === 'init') {
    // Runs once and only once (actually twice with StrictMode) at mount time
  } else if (context === 'naming tbc') {
    // Runs every time the default value is needed
  }
  if (query === null) {
    // Here null means no query in URL
  } else {
    // Unparsed query (failed to parse)
    typeof query === 'string'
  }
  return 42 // Must return the data type of the associated parser
})

In the case of localStorage persistance/caching, which is really only a way to save different URLs and recall them, only performing this recall on init makes sense. But the question remains of what to do in the other cases: the function must return a value for types to be correct, and it cannot throw.

So maybe this API isn't great, and initialization is the only place where things make sense to run a function.

[anaclumos]

+1 to this,

Is is possible to store the nuqs state to local storage and restore it when the user navigates back? So for example

• If I last visited example.com/my-reviews?q=hello
  • This gets saved as {"q": "hello"}
• and navigated somewhere else
• and came back to example.com/my-reviews
  • It will automatically parse local storage and repopulate ?q=hello

[franky47]

Not directly, because:

1. The URL is the source of truth (and falls back to the default value when the key isn't present or when invalid)
2. The default value isn't written to the URL

You can do what you described with effects though.

[mshafir]

I guess in order to do it with an effect though you'd need a way to know if a value is the default because it wasn't specified or if it actually is set in the url as the default value. We could do this ourselves with the raw url string, but it feels like it could be generally useful to be able distinguish that within nuqs.

It's a use case that I have encountered really often. It was something that came built-in with Ember.js (https://guides.emberjs.com/release/routing/query-params/#toc_sticky-query-param-values) and I haven't found anything similar in React. Could be nice even if it's not in nuqs itself, to at least have a recipe for it.

[anaclumos]

@franky47

Just leaving my implementation here.

I do think that in certain cases, I want to "expose" state as URL so that the user can tinker & bookmark it but when the user unknowingly closes and revisits later on, I want to "let them recall" their selections.

So this implementation basically:

• URL Params are still the source of truth. If a user navigates to a page with query params, prioritize that.
• If and only if the user navigates with everything default, repopulate the page with previously-remembered query params.
• Sync the changes to Local Storage.

import { captureException } from "@sentry/nextjs";
import { usePathname } from "next/navigation";
import type { Parser } from "nuqs";
import { useQueryStates } from "nuqs";
import { useEffect, useState } from "react";

type ParsedValue<P> = P extends Parser<infer T> ? T : never;
type ParsedQueriesType<T extends Record<string, Parser<any>>> = {
  [K in keyof T]: ParsedValue<T[K]>;
};

type QueryStateOptions<T extends Record<string, Parser<any>>> = {
  history?: "push" | "replace";
  shallow?: boolean;
  urlKeys?: Partial<Record<keyof T, string>>;
};

export const useQueryStatesWithLocalStorage = <T extends Record<string, Parser<any>>>(
  parsers: T,
  options: QueryStateOptions<T> = {},
) => {
  const pathname = usePathname();
  const [isInitialMount, setIsInitialMount] = useState(true);
  const [queryState, setQueryState] = useQueryStates(parsers, { history: "push", ...options });
  const localStorageKey = `query-state-${pathname}`;

  const areAllValuesDefault = Object.entries(parsers).every(
    ([key, parser]) => queryState[key as keyof T] === (parser as any)?.defaultValue,
  );

  const handleStorage = (state: ParsedQueriesType<T>) => {
    try {
      const params = new URLSearchParams();
      Object.entries(state).forEach(([key, value]) => {
        if (value != null) params.set(key, String(value));
      });
      return params.toString();
    } catch (error) {
      captureException(error);
      return "";
    }
  };

  useEffect(() => {
    if (!isInitialMount) return;

    try {
      const stored = localStorage.getItem(localStorageKey);
      if (stored && areAllValuesDefault) {
        const params = new URLSearchParams(stored);
        const state = {} as Partial<ParsedQueriesType<T>>;

        Object.keys(parsers).forEach((key) => {
          const value = params.get(key);
          if (value) state[key as keyof T] = parsers[key].parse(value) as ParsedValue<T[keyof T]>;
        });

        setQueryState(state);
      }
      setIsInitialMount(false);
    } catch (error) {
      captureException(error);
      setIsInitialMount(false);
    }
  }, [localStorageKey, areAllValuesDefault, isInitialMount, parsers, setQueryState]);

  useEffect(() => {
    if (isInitialMount) return;

    try {
      localStorage.setItem(localStorageKey, handleStorage(queryState as ParsedQueriesType<T>));
    } catch (error) {
      captureException(error);
    }
  }, [queryState, localStorageKey, isInitialMount]);

  return [queryState, setQueryState] as const;
};