nuqs
LightNews LightNews
banner
nuqs.dev
nuqs
@nuqs.dev
320 followers 1 following 69 posts
Type-safe search params state manager for React frameworks.
Like useState, but stored in the URL query string.

Made by @francoisbest.com & contributors

🔗 https://nuqs.dev
Posts Replies Media Videos
nuqs.dev
📦 nuqs@2.7.3 is out! 🚀

- bug fix when passing null to clear a key configured with parseAsArrayOf(...).withDefault([])

- parseAsBoolean is now case-insensitive
→ /?bool=TRUE does what you expect

Try it out: pnpm add nuqs@latest
install nuqs@latest using your favourite package manager
November 7, 2025 at 9:42 PM
nuqs.dev
📦 nuqs has passed 1M weekly downloads on @npmjs.bsky.social 🚀

Thanks everyone! 🫶
Homepage: nuqs.dev 🩷 Fund this package Weekly downloads: 1004771 Version: 2.7.2 License: MIT
October 29, 2025 at 11:57 AM
nuqs.dev
📦 nuqs@2.7.2 is out! 🚀

It includes a bug fix for debounce with `shallow: false` which sent unnecessary stale URL updates to the server.

Try it out: pnpm add nuqs@latest
npm i, {pnpm, yarn, bun} add nuqs@latest
October 16, 2025 at 11:46 AM
nuqs.dev
nuqs has passed 9k stars 🌟

Thank you everyone! 🫶
nuqs stargazers count: 9001 Dragon Ball Z meme: "It's over 9000!"
October 14, 2025 at 3:15 PM
nuqs.dev
📦 nuqs@2.7.1 is out! 🚀

Two rapid-fire PRs by @tkdodo.eu 🔥

- Fixed a bug with MultiParsers & history: push
- Prevent a re-render when doing setState(x => x) (same reference) in useQueryStates

Try it out: pnpm add nuqs@latest
npm i, {pnpm,yarn,bun} add nuqs@latest
October 6, 2025 at 7:17 PM
nuqs.dev
📦 nuqs@2.7.0 is out! 🚀

- MultiParsers: `parseAsNativeArrayOf`, and turn key repetition into Record, Map, Set, anything, with custom parsers. Thanks @tkdodo.eu ! 🙌

- Fixed a bug with flickering optimistic state on update

Try it out: pnpm add nuqs@latest
import { useQueryState, parseAsNativeArrayOf, parseAsInteger } from 'nuqs' const [projectIds, setProjectIds] = useQueryState( 'project', parseAsNativeArrayOf(parseAsInteger) ) // ?project=123&project=456 → [123, 456] Demo: ?nativeArray=123&nativeArray=456&nativeArray=789 [123,456,789]
September 30, 2025 at 3:30 PM
nuqs.dev
📦 nuqs@2.7.0-beta.1 is out! 🚀

✨ MultiParsers allow transforming repeated keys in the URL into more complex data types. This had been a long-requested one, thanks @tkdodo.eu! 🫶

🧪 The testing adapter gets an optional memory to behave more closely to real frameworks.

Try it out: pnpm add nuqs@beta
feat: multi-parsers #1134 PR by TkDodo MultiParsers allow **key repetition** in the URL. E.g.: with the built-in `parseAsNativeArrayOf`: ```ts const [state] = useQueryState('key', parseAsNativeArrayOf(parseAsInteger)) // url: /?key=1&key=2&key=3 // state: [1, 2, 3] ``` Creating custom multi-parsers allow reducing the array of query values into more complex objects: ```ts // /?kv=foo:bar&kv=baz:qux { foo: 'bar', baz: 'qux' } ```
September 26, 2025 at 9:36 PM
nuqs.dev
You can change this default globally at the adapter level if it makes more sense in your case:
nuqs • Send all URL updates to the server <NuqsAdapter defaultOptions={{ shallow: false }}> {children} </NuqsAdapter>
September 19, 2025 at 9:49 PM
nuqs.dev
🔗 Introducing our new domain name: nuqs.dev

2 years ago, I restarted work on the useQueryState hook to support the @nextjs.org app router.

Since then, the project exploded:
⭐ +8k stars
📦 +30M downloads
👥 +50 contributors
🩷 +23 sponsors

Thank you, everyone! 🫶
nuqs.dev Drop the 47ng. Just nuqs. It's cleaner.
September 6, 2025 at 1:42 PM
nuqs.dev
📦 nuqs@2.6.0 is out! 🚀

- ✨ `processUrlSearchParams` middleware: sort the querystring alphabetically (for SEO & cache) or process it before updating the URL.
- 💎 Zod codecs community parser
- ⚠️ Log a warning when using debounce with shallow: true with a link to docs

Try it out: pnpm add nuqs@latest
{npm i, {pnpm,yarn,bun} add} nuqs@latest
September 5, 2025 at 3:06 PM
nuqs.dev
📦 nuqs@2.5.2 is out! 🚀

It fixes a referential stability issue with the testing adapter. The state updater function is now stable across renders & state updates in test environments (@vitest.dev, Jest etc)

Try it out: pnpm add nuqs@latest
install nuqs@latest
August 30, 2025 at 7:17 AM
nuqs.dev
📦 nuqs@2.5.1 is out! 🚀

🐞 It fixes a bug with @cloudflare.social Workers ("Disallowed operation called within global scope"), by lazily creating the throttle queue's AbortController.

TL;DR: you can ship on CFW again now. 🚀

Try it out: pnpm add nuqs@latest
{npm i,{pnpm,yarn,bun} add} nuqs@latest
August 25, 2025 at 2:00 PM
nuqs.dev
To address community feedback and questions, we've updated the Debounce docs to add clarifications.

TL;DR:
- Use debounce with `shallow: false` when doing server-side data fetching (RSCs, gSSP, loaders)
- For client-side fetching (React Query, SWR, tRPC), debounce the returned state instead.
Do I need debounce? Debounce only makes sense for server-side data fetching (RSCs & loaders, when combined with shallow: false), to control when requests are made to the server. For example: it lets you avoid sending the first character on its own when typing in a search input, by waiting for the user to finish typing. The state returned by the hooks is always updated immediately: only the network requests sent to the server are debounced. If you are fetching client-side (eg: with TanStack Query), you’ll want to debounce the returned state instead (using a 3rd party useDebounce utility hook).
August 24, 2025 at 1:41 PM
nuqs.dev
📦 nuqs@2.5.0-beta.7 is out! 🚀

Likely the last beta before shipping 2.5 🤘

- Adds more options to be specified as global defaults on the adapter
- Bundle reduction & deps: nuqs has now zero dependencies!

Follow @tkdodo.eu's advice and try it out:
> pnpm add nuqs@beta
Dominik on stage at React Paris with a slide reading "🙏 Please try out betas & pre-releases"
August 21, 2025 at 11:46 AM
nuqs.dev
📦 nuqs@2.5.0-beta.5 is out! 🚀

It adds a couple of features:
- Change global defaults for options at the adapter level (thanks @tkdodo.eu! 🔥)
- Export package.json for @vite.dev module federation

Try it out: pnpm add nuqs@beta
export function RootLayout({ children }) { return ( // Always send updates to the server 👇 <NuqsAdapter defaultOptions={{ shallow: false }}> {children} </NuqsAdapter> ) }
August 14, 2025 at 3:09 PM
nuqs.dev
📦 nuqs@2.5.0-beta.4 is out! 🚀

It adds a couple of bug fixes:
- Type-safety of default values when using the object signature of useQueryState (thanks @tkdodo.eu 🙌)
- Better compat with older CJS codebases via require(esm)

Try it out: pnpm add nuqs@beta
install nuqs@beta with your favourite package manager
August 13, 2025 at 3:45 PM
nuqs.dev
📦 nuqs@2.5.0-beta.3 is out! 🚀

It adds experimental support for @tanstack.com Router 🏝️🙌

- Use community-based nuqs components in TSR
- Connect nuqs parser definitions to TSR's validateSearch for type-safe linking*

Try it out: pnpm add nuqs@beta
nuqs says “Hello, TanStack Router”, with icons of various projects: Vite, React, React Router, Next.js, Remix, TanStack (circled red) and Vitest. pnpm add nuqs@beta
August 8, 2025 at 1:36 PM
nuqs.dev
🌟 8k stars on @github.com, thank you everyone! 🙌
47ng/nuqs has 8k stars on GitHub
July 24, 2025 at 4:55 AM
nuqs.dev
📦 nuqs@2.5.0-beta.2 is out! 🚀

It adds a couple of features:

- Standard Schema generation: validate & infer types with other tools (tRPC, TanStack Router), using your existing search params definitions
- Strict mode for loaders & cache (see quoted post)

Try it out: pnpm add nuqs@beta
{npm i, pnpm add, yarn add, bun add} nuqs@beta
June 27, 2025 at 6:48 AM
nuqs.dev
📦 nuqs@2.5.0-beta.1 is out! 🚀

The first beta in the 2.5 release line just dropped, with Debounce support: perfect for search inputs, sliders, and server-side updates where you only care about a final value.

Also lots of internal changes, like fixing tearing issues.

Try it out: pnpm add nuqs@beta
{npm i, pnpm add, yarn add, bun add} nuqs@beta
June 11, 2025 at 7:28 PM
nuqs.dev
nuqs has joined the @vercel.com open source program! 🙌

More than the platform credits, the greatest value here will be access to the community, making sure we ship quality updates that benefit all.
▲/?n=u&q=s
May 9, 2025 at 7:17 PM
nuqs.dev
We've passed 7000 stars on GitHub!

🟣 Celebratory stream on Twitch today at 3pm CEST

We'll also play with Debounce, getting it ready for beta next week.

Come say hi! 👋
www.twitch.tv/fortysevenfx
Star emoji with 7k next to it, for the github.com/47ng/nuqs repository
April 15, 2025 at 10:48 AM
nuqs.dev
✨ Testing custom adapters

nuqs now exposes three functions to help test parsers bijectivity, making sure `parse` and `serialize` complement each other, losslessly.
import { isParserBijective, testParseThenSerialize, testSerializeThenParse } from 'nuqs/testing' it('is bijective', () => { // Passing tests return true expect(isParserBijective(parseAsInteger, '42', 42)).toBe(true) // Failing test throws an error expect(() => isParserBijective(parseAsInteger, '42', 47)).toThrowError() // You can also test either side separately: expect(testParseThenSerialize(parseAsInteger, '42')).toBe(true) expect(testSerializeThenParse(parseAsInteger, 42)).toBe(true) // Those will also throw an error if the test fails, // which makes it easier to isolate which side failed: expect(() => testParseThenSerialize(parseAsInteger, 'not a number')).toThrowError() expect(() => testSerializeThenParse(parseAsInteger, NaN)).toThrowError() })
February 17, 2025 at 1:59 PM
nuqs.dev
✨ `parseAsIndex` parser

Your UI should be consistent, and the URL is part of that. That "Page 2" button should give you `/?page=2`.

But unlike humans, JS arrays (and @tanstack.com table) like counting from zero.

Enter parseAsIndex, doing the translation for you.
import { parseAsIndex } from "nuqs"; export function usePageIndex() { const [pageIndex, setPageIndex] = useQueryState( "page" parseAsIndex.withDefault(0), }; // URL is 1-indexed: /?page=1 // state is 0-indexed: pageIndex === 0 }
February 17, 2025 at 1:59 PM
nuqs.dev
We have passed 6k stars on GitHub 🤩

Thank you everyone! 🙏 🚀
6k stars for the github.com/47ng/nuqs repository.
February 4, 2025 at 10:31 AM