nuqs | Type-safe search params state management for Next.js

'use client'

import { parseAsInteger, useQueryState } from 'nuqs'

export function Demo() {
  const [hello, setHello] = useQueryState('hello', { defaultValue: '' })
  const [count, setCount] = useQueryState(
    'count',
    parseAsInteger.withDefault(0)
  )
  return (
    <>
      <button
        onClick={() => setCount(c => c + 1)}
      >
        Count: {count}
      </button>
      <input
        value={hello}
        placeholder="Enter your name"
        onChange={e => setHello(e.target.value || null)}
      />
      <p>Hello, {hello || 'anonymous visitor'}!</p>
    </>
  )
}

Type-safe

End-to-end type safety between Server and Client components.

Universal

Supports both the app router and pages router.

Simple

A familiar React.useState-like API, that syncs with the URL.

Batteries included

Built-in parsers for common state types.

History controls

Replace or append to navigation history and use the Back button to navigate state updates.

Related queries

useQueryStates hook to manage multiple keys at once.

Client-first

Shallow updates by default, opt-in to notify the server to re-render RSCs (with throttle control).

Server cache

Type-safe search params access in nested React Server Components.

Transition

Support for useTransition to get loading states on server updates.

Customizable

Make your own parser and serializer.

Tiny

Only 3.5kb gzipped.

Tested

Tested against every Next.js release.