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!