Features

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 4.07 kB gzipped.

Tested

Tested against every Next.js release.

Sponsors

Used by

N8
N8
@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 O.
@Kingsley_codes
The DX improvement using nuqs for me has been amazing.
We use nuqs pretty much everywhere 🖤
Acropolis1111
Acropolis1111
/u/Acropolis1111
This package is dope
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
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!