nuqs

Pass a typed parser like parseAsInteger or parseAsBoolean as the second argument to useQueryState so the state is typed instead of string | null. Add .withDefault(value) to eliminate null checks throughout the component tree.

Since nuqs v2.5, pass limitUrlUpdates: debounce(300) in the parser's withOptions to debounce URL writes without manual setTimeout logic. For server-driven searches, combine it with shallow: false and useTransition so the server refetches once per typing pause.

Yes, nuqs provides dedicated adapters for React Router v6/v7/v8, Remix, TanStack Router, and plain React via imports like nuqs/adapters/react-router/v7. Non-Next.js adapters also get key isolation, so hooks only re-render when their specific URL key changes.

The most common causes are a missing NuqsAdapter wrapper around the app, a missing 'use client' directive on components using hooks, or a Next.js version below 14.2 which nuqs v2 does not support. Verify the adapter setup and Next.js version first.

Use createSearchParamsCache or createLoader imported from nuqs/server, never from the main nuqs entry which carries a 'use client' directive. In Next.js 15+, searchParams is a Promise, so await the parse call before reading values or calling get() in nested components.

Use history: 'push' for navigation-like state such as pagination, tabs, or modals so the back button undoes the change. Keep the default replace mode for ephemeral state like search text or sliders to avoid flooding browser history with one entry per keystroke.