nuqs | Type-safe search params state management for React

Watch nuqs at

20h

46m

54s

"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 Next.js (app & pages routers), React SPA, Remix, React Router, TanStack Router, and more.

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

Tested & testable

Tested against every Next.js release. Use the provided test adapter to test your components in isolation.

Contributors

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.

Marc Seitz

@mfts0

It’s a database ORM for your URL

Pontus Abrahamsson

@pontusab

We use nuqs pretty much everywhere 🖤

kitze

@thekitze

nuqs is fkn dope

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!

ahmet

@bruvimtired

nuqs has to be one of the best libraries out there. lifting state to the url is so easy now and far better for ux.

Aryan

@AryaAmour08

Just used the nuqs library for the first time today… and wow - syncing URL query params in Next.js has never felt this elegant.
Parsing, defaults, clearOnDefault — it's pretty wild
Where has this been all my life?

Ru Chern Chong

@ruchernchong

Sometimes, there is no need to complicate managing state. nuqs is really powerful.

Bharat Kara

@KaraBharat

nuqs simplifies your URL logic like magic. Seriously.

Ido Evergreen

@IdoEvergreen

It made me realize URL should be part of the design convo not just a place to dump state.
Since I started using nuqs more heavily in production, the way I see and treat URL completely changed.

Rhys Sullivan

@RhysSullivan

The goat library

Virgile Rietsch

@virgilerietsch

best library ever

Dominik Koch

@DominikDoesDev

i love nuqs

Pavel Svitek

@pavelsvitek_

Just did first custom parser today, pretty simple .. great API design 👌