#What is nuqs?

nuqs is a lightweight, type-safe library empowering React developers building modern web apps—especially with Next.js—who need reliable, shareable state persistence without the complexity of global stores or manual URL parsing. Its core value is turning URL query parameters into a seamless source of truth, offering a drop-in replacement for useState that handles synchronization, parsing, and type safety automatically, so you can focus on features while gaining bookmarkable, shareable, and refresh-resilient UIs. Built purely in TypeScript on React hooks with no runtime dependencies beyond your router, it's ideal for use-cases like managing filters and pagination in dashboards, search queries in e-commerce, tab states in multi-view apps, or any scenario where URL-driven state improves UX and collaboration.

#Features ⚡

• useQueryState Hook: Simple, useState-like interface for single params, with automatic URL sync, defaults, and clear-on-default behavior.

• useQueryStates Hook: Batch management of multiple keys in one hook, with atomic updates and reduced re-renders for complex forms or filters.

• Built-in Parsers: Ready serializers for strings, integers, floats, booleans, dates, arrays, and more—plus easy custom parsers for pretty URLs or domain types.

• History & Navigation: Choose shallow (replace) or push updates, fully supporting browser back/forward for natural time-travel UX.

• Server Component Support: Type-safe access to search params in RSCs without prop drilling, with optional throttling for server re-renders.

• Transition Integration: Hook into React's useTransition for pending states during updates, perfect for loading indicators.

• Debug & Test Tools: Built-in logging, performance markers, and test adapters for isolated unit testing of query-dependent components.

#Pros ✅

• Dramatically simplifies URL state with a intuitive API, cutting boilerplate and bugs in filter-heavy apps

• End-to-end TypeScript safety catches errors early, especially valuable in Next.js server/client boundaries

• Performant shallow routing avoids full page reloads, with tiny size keeping bundles lean

• Framework-agnostic flexibility works across the React ecosystem without lock-in

• Strong community momentum and production adoption ensure reliability and quick evolution

#Cons ⚠️

• Adds a dependency for apps with minimal query needs, though its lightness mitigates overhead

• Custom parsers require some setup for highly complex types, adding a small learning step

• Shallow routing defaults might need explicit configuration for server-heavy workflows

#Included Components - Templates

nuqs focuses on powerful hooks rather than visual components, delivering core tools like useQueryState for individual param management with parser options; useQueryStates for multi-param atomic updates and defaults; server cache utilities for RSC param access; custom parser templates for enums, JSON, or domain objects; plus example setups for common patterns like pagination (page/current), sorting (sort/order), and filters (array-based tags)—all with TypeScript generics for seamless integration into your Next.js or Remix projects.

#Pricing 💸

nuqs is completely free and open-source under the MIT license, with no tiers, subscriptions, or premium features—install via npm and use unlimited in personal or commercial projects forever. The project welcomes sponsorships via GitHub Sponsors to support ongoing development, but core access requires zero payment.

#Integrations 🧰

nuqs integrates natively with Next.js (App and Pages Routers) for RSC-aware state; Remix, React Router, and TanStack Router via adapters; plain React SPAs; plus React Server Components for server-side param reads—pair it with TypeScript for full typing and tools like Vercel for deployment.