nuqs
@nuqs.dev
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
Like useState, but stored in the URL query string.
Made by @francoisbest.com & contributors
🔗 https://nuqs.dev
Pinned
🔗 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! 🫶
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! 🫶
Reposted by nuqs
I have an idea for my @reactadvanced.gitnation.org talk that would requiring building and shipping a new feature in @nuqs.dev next week (so I can actually rehearse with it).
Conference-driven development is real.
Conference-driven development is real.
November 15, 2025 at 9:09 PM
I have an idea for my @reactadvanced.gitnation.org talk that would requiring building and shipping a new feature in @nuqs.dev next week (so I can actually rehearse with it).
Conference-driven development is real.
Conference-driven development is real.
Reposted by nuqs
Yesterday I quietly released @nuqs.dev 2.8.0
No big new feature, but a widening of the SemVer range for react-router{-dom} to include v5, as I need it in a client project.
Might be removed in nuqs@3.0.0, we'll see how support goes.
The adapter can be installed with the @shadcn.com CLI:
No big new feature, but a widening of the SemVer range for react-router{-dom} to include v5, as I need it in a client project.
Might be removed in nuqs@3.0.0, we'll see how support goes.
The adapter can be installed with the @shadcn.com CLI:
React Router v5 Adapter | nuqs
Using nuqs in React Router v5 applications.
nuqs.dev
November 18, 2025 at 8:51 AM
Yesterday I quietly released @nuqs.dev 2.8.0
No big new feature, but a widening of the SemVer range for react-router{-dom} to include v5, as I need it in a client project.
Might be removed in nuqs@3.0.0, we'll see how support goes.
The adapter can be installed with the @shadcn.com CLI:
No big new feature, but a widening of the SemVer range for react-router{-dom} to include v5, as I need it in a client project.
Might be removed in nuqs@3.0.0, we'll see how support goes.
The adapter can be installed with the @shadcn.com CLI:
Reposted by nuqs
The @nuqs.dev @shadcn.com registry now has an RSS feed 📡
✨ Get notified when we drop a new adapter, parser or utility
🐞 or when we push updates & bug fixes
nuqs.dev/registry
It now contains community adapters, to one-command install nuqs in:
⛩️ Waku
🐘 Inertia
🥇 One.js
📱 Expo Router (coming soon)
✨ Get notified when we drop a new adapter, parser or utility
🐞 or when we push updates & bug fixes
nuqs.dev/registry
It now contains community adapters, to one-command install nuqs in:
⛩️ Waku
🐘 Inertia
🥇 One.js
📱 Expo Router (coming soon)
November 13, 2025 at 12:13 PM
The @nuqs.dev @shadcn.com registry now has an RSS feed 📡
✨ Get notified when we drop a new adapter, parser or utility
🐞 or when we push updates & bug fixes
nuqs.dev/registry
It now contains community adapters, to one-command install nuqs in:
⛩️ Waku
🐘 Inertia
🥇 One.js
📱 Expo Router (coming soon)
✨ Get notified when we drop a new adapter, parser or utility
🐞 or when we push updates & bug fixes
nuqs.dev/registry
It now contains community adapters, to one-command install nuqs in:
⛩️ Waku
🐘 Inertia
🥇 One.js
📱 Expo Router (coming soon)
📦 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
- 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
November 7, 2025 at 9:42 PM
📦 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
- 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
October 29, 2025 at 11:57 AM
Reposted by nuqs
My talk at @nextjs.org conf is online!
Go watch it, it contains two gems:
- The dangers and limits of URL state (to make you a better engineer)
- A live demo of how @nuqs.dev uses a declarative approach to type-safe and time-safe behaviours, in a composable way.
Go watch it, it contains two gems:
- The dangers and limits of URL state (to make you a better engineer)
- A live demo of how @nuqs.dev uses a declarative approach to type-safe and time-safe behaviours, in a composable way.
Type-safe URL state in Next.js with nuqs
YouTube video by Vercel
www.youtube.com
October 27, 2025 at 11:19 PM
My talk at @nextjs.org conf is online!
Go watch it, it contains two gems:
- The dangers and limits of URL state (to make you a better engineer)
- A live demo of how @nuqs.dev uses a declarative approach to type-safe and time-safe behaviours, in a composable way.
Go watch it, it contains two gems:
- The dangers and limits of URL state (to make you a better engineer)
- A live demo of how @nuqs.dev uses a declarative approach to type-safe and time-safe behaviours, in a composable way.
Reposted by nuqs
Post-conf weekend project: adding support for the @shadcn.com CLI in @nuqs.dev to install:
- parsers
- adapters
- little snippets that make more sense to vendor into your codebase & tweak as needed
First one is the utility I showed in my talk for type-safe linking (with typedRoutes) in @nextjs.org
- parsers
- adapters
- little snippets that make more sense to vendor into your codebase & tweak as needed
First one is the utility I showed in my talk for type-safe linking (with typedRoutes) in @nextjs.org
October 26, 2025 at 6:02 PM
Post-conf weekend project: adding support for the @shadcn.com CLI in @nuqs.dev to install:
- parsers
- adapters
- little snippets that make more sense to vendor into your codebase & tweak as needed
First one is the utility I showed in my talk for type-safe linking (with typedRoutes) in @nextjs.org
- parsers
- adapters
- little snippets that make more sense to vendor into your codebase & tweak as needed
First one is the utility I showed in my talk for type-safe linking (with typedRoutes) in @nextjs.org
📦 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
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
October 16, 2025 at 11:46 AM
📦 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
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
📦 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
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
October 6, 2025 at 7:17 PM
📦 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
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
📦 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
- 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]](https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:bw4kguuz764ponbbn2aaycxk/bafkreigc4spz7pnbvvnki4zsegvq6tq5foypcrc2rptzaokg3obunzjsde@jpeg)
September 30, 2025 at 3:30 PM
📦 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
- 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
📦 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
✨ 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'
}
```](https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:bw4kguuz764ponbbn2aaycxk/bafkreiakudkqqnomzxzor65qy6fgpjspxtejtxqjcr3priivkootchhjta@jpeg)
September 26, 2025 at 9:36 PM
📦 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
✨ 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
Reposted by nuqs
Relive the brilliance of #ReactParis 2025! 🌟
Catch up on last conf's unforgettable sessions:
➡️ Type Safe URL State Management in #React with nuqs -by- @francoisbest.com
🎞️ www.youtube.com/watch?v=U__R...
😉 See you next March 2026 👉🏽 react.paris
Catch up on last conf's unforgettable sessions:
➡️ Type Safe URL State Management in #React with nuqs -by- @francoisbest.com
🎞️ www.youtube.com/watch?v=U__R...
😉 See you next March 2026 👉🏽 react.paris
Type Safe URL State Management in React with nuqs - François Best
YouTube video by BeJS
www.youtube.com
September 24, 2025 at 12:05 PM
Relive the brilliance of #ReactParis 2025! 🌟
Catch up on last conf's unforgettable sessions:
➡️ Type Safe URL State Management in #React with nuqs -by- @francoisbest.com
🎞️ www.youtube.com/watch?v=U__R...
😉 See you next March 2026 👉🏽 react.paris
Catch up on last conf's unforgettable sessions:
➡️ Type Safe URL State Management in #React with nuqs -by- @francoisbest.com
🎞️ www.youtube.com/watch?v=U__R...
😉 See you next March 2026 👉🏽 react.paris
Reposted by nuqs
@nuqs.dev v3 will likely require @react.dev 19.
We managed to work around not using `useOptimistic` with hacks, but to properly support optimistic local state updates while the URL update is queued, with concurrent rendering & Suspense, we need to do it the right way.
We managed to work around not using `useOptimistic` with hacks, but to properly support optimistic local state updates while the URL update is queued, with concurrent rendering & Suspense, we need to do it the right way.
September 23, 2025 at 1:17 PM
@nuqs.dev v3 will likely require @react.dev 19.
We managed to work around not using `useOptimistic` with hacks, but to properly support optimistic local state updates while the URL update is queued, with concurrent rendering & Suspense, we need to do it the right way.
We managed to work around not using `useOptimistic` with hacks, but to properly support optimistic local state updates while the URL update is queued, with concurrent rendering & Suspense, we need to do it the right way.
Reposted by nuqs
I need to get better at SEO.
A lot of folks can't remember the name `nuqs`, but know what it's about, and can't find it with search terms.
Neither the docs, the GitHub repo, nor the NPM package page rank for some critical keywords.
A lot of folks can't remember the name `nuqs`, but know what it's about, and can't find it with search terms.
Neither the docs, the GitHub repo, nor the NPM package page rank for some critical keywords.
September 23, 2025 at 7:29 PM
I need to get better at SEO.
A lot of folks can't remember the name `nuqs`, but know what it's about, and can't find it with search terms.
Neither the docs, the GitHub repo, nor the NPM package page rank for some critical keywords.
A lot of folks can't remember the name `nuqs`, but know what it's about, and can't find it with search terms.
Neither the docs, the GitHub repo, nor the NPM package page rank for some critical keywords.
Reposted by nuqs
I sat down with @kapehe.bsky.social to chat about @nuqs.dev, open-source, community, and desserts 🍰
Open Source Stories S1E3
www.youtube.com/watch?v=9PJx...
Open Source Stories S1E3
www.youtube.com/watch?v=9PJx...
Open Source Stories: nuqs
YouTube video by Vercel
www.youtube.com
September 22, 2025 at 7:46 PM
I sat down with @kapehe.bsky.social to chat about @nuqs.dev, open-source, community, and desserts 🍰
Open Source Stories S1E3
www.youtube.com/watch?v=9PJx...
Open Source Stories S1E3
www.youtube.com/watch?v=9PJx...
Why do nuqs URL updates occur client-side only by default?
Because you're guaranteed to run @react.dev on the client, but not all frameworks do SSR.
With `shallow: false`, you opt-out of this client-only behaviour, and cross the network boundary for search params you need during SSR.
Because you're guaranteed to run @react.dev on the client, but not all frameworks do SSR.
With `shallow: false`, you opt-out of this client-only behaviour, and cross the network boundary for search params you need during SSR.
September 19, 2025 at 9:45 PM
Why do nuqs URL updates occur client-side only by default?
Because you're guaranteed to run @react.dev on the client, but not all frameworks do SSR.
With `shallow: false`, you opt-out of this client-only behaviour, and cross the network boundary for search params you need during SSR.
Because you're guaranteed to run @react.dev on the client, but not all frameworks do SSR.
With `shallow: false`, you opt-out of this client-only behaviour, and cross the network boundary for search params you need during SSR.
Imagine a local-first, distributed, peer-to-peer, immutable data exchange system.
This is not BitTorrent.
It’s what you get from putting your app state in the URL.
This is not BitTorrent.
It’s what you get from putting your app state in the URL.
September 16, 2025 at 8:22 PM
Imagine a local-first, distributed, peer-to-peer, immutable data exchange system.
This is not BitTorrent.
It’s what you get from putting your app state in the URL.
This is not BitTorrent.
It’s what you get from putting your app state in the URL.
Reposted by nuqs
🗣️ Big news: I'll be speaking at @nextjs.org Conf '25, on Oct 22 in SF !
We'll cover a few tricks @nuqs.dev has up its sleeve to scale URL state in Next.js (some I yet need to finish building 😅).
So thankful for the opportunity 🙌
We'll cover a few tricks @nuqs.dev has up its sleeve to scale URL state in Next.js (some I yet need to finish building 😅).
So thankful for the opportunity 🙌
September 15, 2025 at 7:18 PM
🗣️ Big news: I'll be speaking at @nextjs.org Conf '25, on Oct 22 in SF !
We'll cover a few tricks @nuqs.dev has up its sleeve to scale URL state in Next.js (some I yet need to finish building 😅).
So thankful for the opportunity 🙌
We'll cover a few tricks @nuqs.dev has up its sleeve to scale URL state in Next.js (some I yet need to finish building 😅).
So thankful for the opportunity 🙌
Reposted by nuqs
September 10, 2025 at 7:52 PM
🔗 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! 🫶
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! 🫶
September 6, 2025 at 1:42 PM
🔗 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! 🫶
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@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
- ✨ `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
September 5, 2025 at 3:06 PM
📦 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
- ✨ `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
Reposted by nuqs
Absolutely love Nuqs. I don’t leave home without it!
September 3, 2025 at 8:46 PM
Absolutely love Nuqs. I don’t leave home without it!