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

'use client'

import { useQueryState } from 'nuqs'
import { z } from 'zod'

export function Demo() {
  const [hello, setHello] = useQueryState('hello', { defaultValue: '' })
  const [count, setCount] = useQueryState('count', {
    parse: z.coerce
      .number()
      .int()
      .default(0)
      .catch(({ input = 0 }) => {
        if (typeof input !== 'number') return 0 // Somehow it can be a string
        if (Number.isNaN(input)) return 0
        return Math.floor(input)
      }).parse,
    defaultValue: 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 & serializers 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. No prop drilling needed.

Transition

Support for useTransition to get loading states on server updates.

Customizable

Make your own parser and serializer.

Tiny

Only 3.64 kB gzipped.

Tested

Tested against every Next.js release.

Used by

openpanel.dev

@nathanbrachotte

I started building my own hook helpers for handling URL states and had to deal with some performance drawbacks.
Eventually stumbled on this little beauty and it has everything I wanted and more.

Kingsley O.

@Kingsley_codes

The DX improvement using nuqs for me has been amazing.

Pontus Abrahamsson

@pontusab

We use nuqs pretty much everywhere 🖤

Marc Seitz

@mfts0

It’s a database ORM for your URL

Darathor17

thx a lot for this awesome library! I was syncing with URL like nextjs recommends .. performance are awful and I was about to move back to useState.

KafKa

@KafKa303

This is a great idea, way better than calling useSearchParam and cook my own stuff! nuqs is such a important last piece for app router! An extremely underrated lib!