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 bassis, 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:

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

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.