nuqs

nuqs is a type-safe search params state manager for React and its major frameworks. It gives you a hook that behaves just like React.useState, except the state lives in the URL’s query string — making it shareable, bookmarkable, and navigable with the browser’s Back and Forward buttons.

Built around a small set of composable parsers and framework adapters, nuqs supports Next.js (app and pages routers), plain React SPAs, Remix, React Router, and TanStack Router. It handles serialization, batching, shallow updates, and server-side access to search params without forcing you to write brittle string-parsing code by hand.

What You Get

• A useState-compatible hook (useQueryState) whose value is persisted in the URL query string.
• A companion useQueryStates hook for managing several related query keys as one object.
• Built-in, composable parsers for integers, floats, booleans, dates, arrays, JSON, and string/number literals and enums.
• Framework adapters for Next.js (app and pages), plain React, Remix, React Router, and TanStack Router.
• Server-side helpers (createSearchParamsCache, loaders, serializers) for type-safe searchParams access in server components.

Common Use Cases

• Persisting filters, search terms, tabs, and pagination in the URL so views are shareable and bookmarkable.
• Driving table and dashboard state (sorting, page size, selected rows) from query params.
• Building deep-linkable UI where the Back button navigates between prior states.
• Sharing type-safe searchParams between client components and Next.js server components.

Under The Hood

Architecture — The public surface is intentionally thin: useQueryState (src/useQueryState.ts) is a small wrapper that delegates to useQueryStates (src/useQueryStates.ts), so single- and multi-key state share one code path. Reading and writing the URL is abstracted behind an adapter layer (src/adapters/*) with implementations for Next.js app/pages routers, plain React, Remix, React Router v5–v8, and TanStack Router, all wired through a shared React context (src/adapters/lib/context.ts). Updates are debounced and batched through an emitter and history-patching layer (src/adapters/lib/patch-history.ts, src/lib/emitter.ts) so several hooks updating in the same tick produce a single URL change, and a server module (src/index.server.ts, src/cache.ts, src/loader.ts, src/serializer.ts) exposes the same parsers for type-safe searchParams access outside React.

Tech Stack — Written entirely in TypeScript with a single runtime dependency, @standard-schema/spec, which lets parsers interoperate with validation libraries like Zod, Valibot, and ArkType. React and the various routers are declared as optional peer dependencies (react >=18.2, next >=14.2, react-router ^5–^8, @tanstack/react-router ^1, @remix-run/react >=2), so nuqs adds almost nothing to your bundle. It is built with tsdown and size-limited with @size-limit/preset-small-lib.

Code Quality — The package is thoroughly tested: unit tests cover parsers, the serializer, the cache, the loader, and standard-schema integration, while browser-based tests (Vitest + Playwright) exercise the hooks and each adapter against real navigation. Property-based testing via fast-check hardens the URL encoding and parser logic, and the public API is snapshot-guarded (api.test.ts). Naming is consistent and the type overloads for useQueryState are carefully ordered from most to least specific to preserve inference.

API Design — The core design goal is familiarity: if you know React.useState, you already know nuqs. Parsers compose fluently (parseAsInteger.withDefault(0), parseAsArrayOf(parseAsInteger)), and the same parser definitions are reused for both client hooks and server-side caches, so there is one mental model across the stack. Getting started requires only wrapping the tree in the framework’s NuqsAdapter, and the documentation at nuqs.dev is extensive with runnable examples.