Troubleshooting

Pages router

Because the Next.js pages router is not available in an SSR context, this hook will always return null (or the default value if supplied) on SSR/SSG.

This limitation doesn’t apply to the app router.

Caveats

Different parsers on the same key

Hooks are synced together on a per-key basis, so if you use different parsers on the same key, the last state update will be propagated to all other hooks using that key. It can lead to unexpected states like this:

const [int] = useQueryState('foo', parseAsInteger)
const [float, setFloat] = useQueryState('foo', parseAsFloat)
 
setFloat(1.234)
 
// `int` is now 1.234, instead of 1

We recommend you abstract a key/parser pair into a dedicated hook to avoid this, and derive any desired state from the value:

function useIntFloat() {
  const [float, setFloat] = useQueryState('foo', parseAsFloat)
  const int = Math.floor(float)
  return [{int, float}, setFloat] as const
}

Client components need to be wrapped in a <Suspense> boundary

You may have encountered the following error message from Next.js:

Missing Suspense boundary with useSearchParams

Components using hooks like useQueryState should be wrapped in <Suspense> when rendered within a page component. Adding the ‘use client’ directive to the page.tsx file is the immediate fix to get things working if you are defining components that use client-side features (like nuqs or React Hooks):

'use client'
 
export default function Page() {
  return (
    <Suspense>
      <Client />
    </Suspense>
  )
}
 
function Client() {
  const [foo, setFoo] = useQueryState('foo')
  // ...
}

However, the steps below indicate the optimal approach to get better UX: separating server and client files (and moving client side code as low down the tree as possible to pre-render the outer shell).

The recommended approach is:

1. Keep page.tsx as a server component (no 'use client' directive)
2. Move client-side features into a separate client file.
3. Wrap the client component in a <Suspense> boundary.