How to Implement useQueryState Similar to Nuqs

[sagardwivedi]

I'm working on implementing a useQueryState hook that is similar in functionality to Nuqs but utilizing @tanstack/react-router for handling query parameters. The implementation involves a Parser utility for parsing and stringifying different data types (string, number, boolean) and a hook that syncs state with query parameters.

Here is the current implementation:

import { useRouter, useSearch } from "@tanstack/react-router";
import { useMemo } from "react";

export type Parser<T> = {
  parse: (value: string | null) => T | null;
  stringify: (value: T | null) => string | null;
};

export const stringParser: Parser<string> = {
  parse: (value) => value ?? null,
  stringify: (value) => value ?? null,
};

export const numberParser: Parser<number> = {
  parse: (value) => (value ? parseFloat(value) : null),
  stringify: (value) => (value !== null ? String(value) : null),
};

export const booleanParser: Parser<boolean> = {
  parse: (value) =>
    value === "true" ? true : value === "false" ? false : null,
  stringify: (value) => (value !== null ? String(value) : null),
};

export const useQueryState = <T>(
  key: string,
  parser: Parser<T>,
  defaultValue: T | null = null
): [T | null, (value: T | null) => void] => {
  const router = useRouter();
  const searchParams = useSearch({ strict: false });

  const value = useMemo(() => {
    const paramValue = searchParams[key as keyof typeof searchParams];
    return parser.parse(paramValue ? String(paramValue) : null) ?? defaultValue;
  }, [searchParams, key, parser, defaultValue]);

  const setValue = (newValue: T | null) => {
    router.navigate({
      search: (prev) => {
        return {
          ...prev,
          [key]: parser.stringify(newValue),
        };
      },
    });
  };

  return [value, setValue];
};

I would like feedback on the following:

• Are there any edge cases that I might be missing in the parser logic?
• How could this be further optimized for performance and reusability?
• Is there a better way to handle nested query parameters or complex data structures?

Additionally, my current implementation is throwing type errors, particularly related to the parser logic and the handling of search parameters. Any insights into resolving these type issues while maintaining the intended functionality would be greatly appreciated.

[franky47]

Hi, I'm the author of nuqs, FYI we have a PR to support TanStack Router: 47ng/nuqs#953. Feedback on it would be welcome!

There are a few differences between nuqs & TSR:

• nuqs defines parsing & serialising per key, whereas TSR does it globally (which might relate to your type errors)
• nuqs doesn't have strong opinions on how to scope search params definitions (at the component level vs page level), unlike TSR which has page-level hierarchical definitions, allowing for type-safe routing.
• A good part of what nuqs does (aside from SerDe & state sync) is decoupling optimistic state and throttled URL updates to alleviate browsers rate-limiting the History API. I'm not sure how this is handled by TSR.

[sagardwivedi]

Thanks @franky47 for reaching out and sharing that! The PR sounds interesting, and the breakdown of how nuqs and TanStack Router differ is super helpful. I can definitely see how the global vs. per-key parsing approach could be affecting the type issues I’m seeing. Also, the way nuqs handles optimistic state and throttled URL updates is a smart approach — I hadn’t considered the impact of browser rate limits.

I’ll check out the PR and let you know if I have any feedback. Appreciate you taking the time to explain it!

[maelp]

I'm also interested by this, it's not clear to me how Tanstack Router search params methods and NUQS relate/complement each other? Are they doing the same?

By quickly reading the Tanstack Router doc I have the impression that the path suggested by Tanstack (eg when modifying filters on a table that we want to have reflected in the URL) is

input -> change URL params -> this triggers the change of state

rather than

input -> triggers a change of state -> this is synchronized (without reload) in the URL

are both Tanstack and Nuqs doing that? Am I misunderstanding something? Which would be the better way to do this and why?

Are TSR and Nuqs complementary (as far as search-params are concerned) or serving identical purposes, and one should rather choose one or the other?

[franky47]

are both Tanstack and Nuqs doing that? Am I misunderstanding something? Which would be the better way to do this and why?

Not sure about TSR, but nuqs does the second approach (immediate local state update, and queues the URL update to handle rate limiting of the History API).

Are TSR and Nuqs complementary (as far as search-params are concerned) or serving identical purposes, and one should rather choose one or the other?

TSR is a complete router solution, while nuqs only provides a search params abstraction on top of other existing routers. While you can now use nuqs within TanStack Router apps, it comes with caveats and I'd recommend using the TSR APIs in application code.

[maelp]

@franky47 thanks! So in TSR it would be the first route right? input -> set search param -> triggers route re-render? I'm not sure if I'm understanding the Tanstack router approach for this correctly, can't seem to find any full-fledged example

[franky47]

This is a PR to keep an eye on, which could bring a nuqs-like API built-in TSR/TSS: #4552