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, 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

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

It’s a database ORM for your URL

Pontus Abrahamsson

We use nuqs pretty much everywhere 🖤

kitze

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.

ahmet

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

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

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

Bharat Kara

nuqs simplifies your URL logic like magic. Seriously.

Ido Evergreen

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

The goat library

Virgile Rietsch

best library ever

Dominik Koch

i love nuqs

Josh tried coding

nuqs is one of my favorite pieces of software recently. don't mean to glaze but man, it's a type-safe, way better version of react state

Pavel Svitek

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

OrcDev

Keep it up guys! You're doing a great job!
I'm using nuqs on real projects in production already, it's amazing how easy it is to control URL params.

Brandon McConnell

nuqs is the perfect solution to the epidemically annoying problem of query param state management
I wish I had this 10 years ago

Iza

goated library

Code With Antonio

i am so happy every time i get to use nuqs!

arth

also, nuqs is amazing

Mr T.

one of the most useful pieces of library ever made
thx for making our life easier as devs and ux way better for our users

Hayden Bleasel

deez nuqs

Christopher Burns

Really glad to finally met Francois from nuqs! I love using it!

Chánh Đại

I integrated nuqs into an internal project, and it helped simplify filter-related query logic and reduce development time.

Abhishek Chauhan

Big fan of nuqs!

Michael

meeting the guy behind nuqs was insane. it's one of those tools literally every web dev should know about

James Perkins

nuqs is so goated

dmytro

thank you for your hard work 🫶
nuqs is awesome

Suraj Jha

Currently Using nuqs to add some pagination and searching feature into my nextjs app and i am loving it

shibbi

We started using nuqs and achieved world peace internally.

Ajay Patel

Big thanks to nuqs for making URL state management actually enjoyable! 🙌

useState but synced with the URL? ✅
Type-safe? ✅
Works everywhere (Next.js, Remix, React Router)? ✅
Only 6kb? ✅

Happy to support such a well-crafted library 😇

anarki supreme

I LOVE NUQS I LOVE PARAMS THAT JUST WORK AHAHA WOOHOOO❤️❤️❤️❤️

Matt

this is a huge time saver 😍 nuqs is literally the first thing i add to a project after some basic ui like tabs & toggles