nuqs | Type-safe search params state management for React

"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, 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 5.5 kB gzipped.

Tested & testable

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

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!