Documentation Playground Registry Blog

Getting started

Installation Adapters Basic usage

Guide

Options useQueryStates Server-Side usage Limits

Going further

Utilities Debugging Testing Troubleshooting SEO Tips and tricks About Changelog Migration guide to v2

nuqs@2.9.0

Documentation Playground Registry Blog

Changelog

What's new in nuqs.

v2.9.0

Published on 2026-06-30•View on GitHub

Features

#1437·add support for react-router v8·by franky47
#1451·add history to adapters defaultOptions·by manojVivek

Bug fixes

#1318·cross-page transitions in TanStack Router·by franky47
#1334·stale URL value when revisiting a page under Next.js cacheComponents·by franky47
#1366·prevent infinite re-renders with TSR viewport preloading·by franky47
#1368·wrong transient state in next/app when updating in useEffect·by franky47
#1445·stale value under Activity·by franky47
#1450·stale search params leaking across React Router navigation·by franky47

Documentation

#1222·add registry metadata·by taro-yanagiya
#1256·add changelog page·by rajanarahul93
#1351·strip Fumadocs inline code syntax highlighting hints from LLM markdown·by franky47
#1353·update recharts & replace partialLine implementation·by franky47
#1356·add Sentry and Syntax.fm as sponsors 💖·by franky47
#1357·add 1771 Technologies as a sponsor 💖·by franky47
#1362·update images alt attributes·by franky47
#1364·extrapolate missing NPM stats data·by franky47
#1376·add attribution footer in LLM docs·by franky47
#1383·add 1771 Technologies as sidebar sponsor·by franky47
#1400·add redirect from /changelog to /docs/changelog·by franky47
#1406·add brand assets context menu·by TheOrcDev
#1409·add TradingGoose as a sponsor 💖·by franky47
#1414·add Upstash as a sponsor 💖·by mezotv
#1415·add CodeRabbit as a sponsor 💖·by mezotv
#1416·use www.usenotra.com for Notra sponsor link·by mezotv
#1418·tighter sponsors grid·by franky47
#1432·changelog reads DTO from releases·by franky47
#1438·add Deno & other package managers to install instructions·by bartlomieju
#1441·theme-aware shieldcn badges + wordmark header·by jal-co
#1447·trim down llm content·by franky47
#1456·add Loops as a sponsor 💖·by franky47
#1457·strip unreleased headings from the production ToC·by franky47
#1461·fix shallow updates "Invalid URL" crash·by franky47
9cb051fc·reorder & tweak readme badges·François Best
e9cd8f7c·fix contributors link in README·François Best
f48b3908·fix wordmark on npmx.dev & npmjs.com·François Best
6722fe05·fix react router logos in README·François Best

Other changes

#1154·add Knip for upkeeping·by franky47
#1176·split debug logs to reduce bundle size·by franky47
#1346·add discussion participants to thanks section in release notes·by franky47
#1347·bump actions/upload-artifact from 6.0.0 to 7.0.0·by dependabot
#1354·disable pnpm cache in deployment job·by franky47
#1360·upgrade vite to v8.0.0·by franky47
#1367·reduce test verbosity for agents·by franky47
#1370·history API updates location.search synchronously·by franky47
#1371·update Next.js to 16.2.0·by franky47
#1372·test docs against new versions of Next.js·by franky47
#1373·bump effect from 3.19.15 to 3.20.0·by dependabot
#1379·bump actions/setup-node from 6.2.0 to 6.3.0·by dependabot
#1386·remove Sentry·by franky47
#1387·harden Next.js canary test workflows·by franky47
#1390·upgrade to knip 6·by franky47
#1393·harden CI/CD workflow against supply-chain and injection vectors·by franky47
#1394·fix npm pkg set command·by franky47
#1396·bump actions/upload-artifact from 7.0.0 to 7.0.1·by dependabot
#1398·update to pnpm 11·by franky47
#1403·split CD step into publish + release notes generation·by franky47
#1405·explictly no cache on publish job·by franky47
#1407·don't persist credentials on checkout·by franky47
#1408·bump turbo from 2.8.2 to 2.9.14·by dependabot
#1411·apply minimumReleaseAgeExclude for next only where relevant·by franky47
#1412·inline pre/post scripts·by franky47
#1413·simplify knip config·by franky47
#1417·npm staged publishing·by franky47
#1419·bump next to 16.2.7·by franky47
#1420·fix flaky #1099 unit tests·by franky47
#1422·update actions-slack-notify·by franky47
#1423·add reproducible build tools for staged package review·by franky47
#1426·finalize release·by franky47
#1427·stop passing router hooks through context·by franky47
#1429·remove dry-run rehearsal from release-draft·by franky47
#1430·milestone automation - drop shipping next, automate backlog·by franky47
#1431·bump react-router from 7.13.0 to 7.18.0·by dependabot
#1434·don't run Lint PR Title on merged PRs and body-only edits·by franky47
#1435·replace MailPace SDK with minimal implementation·by franky47
#1436·pnpm dedupe·by franky47
#1439·add invitation to try betas on release comments·by franky47
#1440·verify production tags locally·by franky47
#1442·allow finalize to comment on related discussions·by franky47
#1443·split release notes gen from release draft·by franky47
#1446·scope nullable useSearchParams defence to Next.js specific adapter·by franky47
#1452·emit the release-notes multiline output from TypeScript·by franky47
#1453·require sha512 integrity as the primary release-verification gate·by franky47
#1454·unify the repo on the next branch·by franky47
#1455·replace husky with native Git config hooks·by franky47
#1459·refresh the docs on a GA release via ISR tag invalidation·by franky47
d8dd8c7b·ignore local worktrees·François Best
514ae3de·update funding options·François Best
e40d4527·disable ci-cd publishing steps·François Best
66a7eba2·try GitHub release notes generation·François Best
0be5dca4·always run release notes gen·François Best
281a0f04·keep npm --json stdout clean and harden stage-id parsing·François Best
9a3e12b0·surface staged tarball shasum & integrity in release summary·François Best
0dd152ad·fix executable bit for release-finalize.ts·François Best
fc1d1ee6·add temporary manual trigger for release-finalize·François Best
9a0a0ad9·revert fc1d1ee6·François Best
44d31d78·fix worktree directory reference in .gitignore·François Best

Contributors

+9

AnthonyYashchuk, AyushNigam-1, bartlomieju, and 14 other contributors

v2.8.9

Published on 2026-02-27•View on GitHub

Bug fixes

#1329·update TSR to latest, using navigate from useRouter·by franky47
#1344·use process.env.DEBUG for server-side debug detection·by ryannguyen95

Documentation

#1328·prevent layout overflow in mobile landing demo·by bforbilly24
#1337·fix quotes avatar urls·by franky47

Other changes

#1324·test Next.js cacheComponents in CI·by franky47
#1325·disable sourcemap errors for RRv7 & Remix·by franky47
#1326·fix trpc tsc errors by bumping react-router deps·by franky47
#1327·update dependencies·by franky47
#1332·add custom Playwright reporter·by franky47
#1333·only apply cacheComponents to Next.js 16·by franky47
6e5b4f3f·test cacheComponents against Next.js canaries·François Best
a69bce6b·progressive AGENTS.md disclosure·François Best

Contributors

bforbilly24, devphucnguyen, PaulRBerg, and ryannguyen95

v2.8.8

Published on 2026-02-02•View on GitHub

Bug fixes

#1320·reset queue after updates in Next.js app router·by franky47

Other changes

#1267·bump @trpc/server from 11.5.0 to 11.8.0·by dependabot
#1321·bump actions/checkout from 6.0.1 to 6.0.2·by dependabot
#1322·bump actions/setup-node from 6.1.0 to 6.2.0·by dependabot

Contributors

BlastyCZ, felix-quotez, l0gicgate, and 3 other contributors

v2.8.7

Published on 2026-01-30•View on GitHub

Bug fixes

#1316·wait for navigation in RR adapters before syncing·by franky47

Documentation

#1271·add LLM features (copy as markdown, open button, llms.txt)·by mezotv
#1279·add shadcnstudio as featured sponsor 💖·by franky47
#1280·add quotes & fix shadcn/studio logo·by franky47
#1281·make sure nextjs weekly switches color·by mezotv
#1283·add Rhys Sullivan as sponsor 💖·by franky47
#1284·OSS Pledge details·by franky47
#1286·users leaderboard·by franky47
#1287·update twitch handle·by franky47
#1290·2025·by franky47
#1291·switch favicon in development·by franky47
#1292·add release calendar·by franky47
#1297·add Brandon McConnell as sponsor 💖·by franky47
#1298·add Ru Chern Dong as sponsor 💖·by franky47
#1299·add David Haz as sponsor 💖·by franky47
#1300·add basedanarki as sponsor 💖·by franky47
#1301·change dominik koch founder url to notra·by mezotv
#1302·add Hayden Bleasel as a sponsor 💖·by franky47
#1305·fix ISO week year calculation at year boundaries·by copilot-swe-agent
#1310·fix partial line·by franky47
914b0b2a·remove log·François Best

Other changes

#1269·Replace Cypress with Playwright for e2e tests·by franky47
#1282·check PR titles against core changes·by franky47
#1288·fix release note formatting issues, add tests·by franky47
#1294·bump actions/checkout from 6.0.0 to 6.0.1·by dependabot
#1295·bump actions/upload-artifact from 5.0.0 to 6.0.0·by dependabot
#1296·bump actions/setup-node from 6.0.0 to 6.1.0·by dependabot
#1306·bump @react-router/node from 7.8.1 to 7.9.4·by dependabot
#1307·bump @remix-run/react from 2.17.0 to 2.17.3·by dependabot
#1309·bump react-router from 7.8.1 to 7.12.0·by dependabot
#1311·use distributed turbo.json package configurations·by anthonyshew
#1314·update React & Next.js deps (CVE-2026-23864)·by franky47
#1317·add repro 1293 for Next.js·by franky47
a4b74baf·add logos·François Best

Contributors

+1

anthonyshew, dreyks, IllMind11, and 6 other contributors

v2.8.6

Published on 2025-12-23•View on GitHub

Bug fixes

#1275·export CreateLoaderOptions type·by guisehn

Documentation

#1266·fix broken images·by franky47
#1268·add full number to NPM stats title·by franky47

Other changes

#1264·update dependencies (2025-12-11 React CVEs)·by franky47
ebcdd34f·disable shallow test in the pages router in Next.js latest·François Best

Contributors

guisehn

v2.8.5

Published on 2025-12-10•View on GitHub

Bug fixes

#1262·undefined means "leave as-is" in useQueryStates·by franky47

v2.8.4

Published on 2025-12-08•View on GitHub

Bug fixes

#1258·remove 'use client' directive in .d.ts definition files·by Morabotti
#1259·remove prebuild step failing on Windows·by franky47

Other changes

#1254·Vitest Browser Mode·by ntatoud

Contributors

Morabotti and ntatoud

v2.8.3

Published on 2025-12-05•View on GitHub

Bug fixes

#1250·forward processUrlSearchParams through the debounce queue·by franky47

Documentation

#1238·landing page tweaks·by franky47
#1240·add Databuddy for web analytics·by franky47
3f914668·fix Inertia adapter·KapishDima
327f0c40·remove React Advanced banner·François Best

Other changes

#1225·bump @sentry/nextjs from 10.20.0 to 10.27.0·by dependabot
#1235·bump actions/checkout from 5.0.0 to 6.0.0·by dependabot
#1239·bump next to 16.0.7·by mezotv
#1243·bump express from 4.21.2 to 4.22.0·by dependabot

Contributors

joschka-w and mezotv

v2.8.2

Published on 2025-12-01•View on GitHub

Bug fixes

#1226·inject version in prepack step·by franky47

Documentation

#1228·add React Advanced banner & linktree·by franky47
#1230·oss-pledge·by franky47
#1234·add Dominik Koch as sponsor 💖 and move to flex layout·by mezotv
#1236·add title to Dominik Koch 💖·by mezotv
#1237·add Databuddy as sponsor 💖·by mezotv
e78ace47·fix og:image for oss pledge·François Best
50158702·fix overflow on mobile·François Best
4b9a0adc·add slides for React Advanced·François Best
01c12075·update slides·François Best

Other changes

#1227·bump valibot from 1.1.0 to 1.2.0·by dependabot

Contributors

mezotv

v2.8.1

Published on 2025-11-21•View on GitHub

Bug fixes

#1217·pass in full pathname + search in TSR to avoid trailing slashes·by franky47

Contributors

andreastande, mirshko, and SeanCassiere

v2.8.0

Published on 2025-11-17•View on GitHub

Features

#1214·add react-router v5 support·by franky47

Documentation

#1206·add Next.js Weekly sponsor 💖·by franky47
#1209·assemble shadcn registry items from remote sources·by franky47
#1210·add @pqoqubbw as sponsor 💖·by franky47
#1211·fix SVG props·by franky47
#1212·registry error handling·by franky47
#1213·add community adapter listing·by franky47
8535fd65·fix broken links·François Best
27727601·fix pfp for Chris Burns·François Best

Other changes

#1208·generate release notes & clear Shipping Next·by franky47
b16fab28·only edit release notes after a publish·François Best
277a9487·install script deps·François Best
b334dc3a·don't run other release note steps when no deploy·François Best
a90daeb6·add step summary in milestone automation·François Best
c084f91a·add issue/pr links·François Best
f28d1ffc·fix null·François Best

v2.7.3

Published on 2025-11-07•View on GitHub

Bug fixes

#1197·TypeError in serializer for array with default value·by janglad
#1204·make parseAsBoolean case insensitive·by joshuaobrien

Documentation

#1182·add shadcn registry·by franky47
#1185·remove Next.js conf banners·by franky47
#1186·add quotes from friends 🫶·by franky47
#1187·add X/Twitter & order social links·by franky47
#1189·add doc page for shadcn registry·by franky47
#1190·add more testimonials·by franky47
#1191·use trusted shadcn registry·by franky47
#1192·add registry page metadata·by franky47
#1200·caching tweaks·by franky47
#1205·revert cacheComponents·by franky47
8284cdb4·fix registry item path·François Best

Other changes

#1170·update to Next.js 16·by franky47
#1178·update recharts to v3·by franky47
#1181·bump vite from 7.1.5 to 7.1.11·by dependabot
#1194·bump actions/upload-artifact from 4.6.2 to 5.0.0·by dependabot
#1195·bump actions/setup-node from 5.0.0 to 6.0.0·by dependabot
#1196·bump pnpm/action-setup from 4.1.0 to 4.2.0·by dependabot
#1198·bump vite from 5.4.20 to 7.1.12·by dependabot
#1207·update dependencies in preparation for OIDC trusted publishing·by franky47
1f675dd0·remove email from linktree·François Best
08cd69cc·remove duplicate CI step·François Best
866bce4b·burst ISR cache only on master deployments·François Best

Contributors

janglad and joshuaobrien

v2.7.2

Published on 2025-10-16•View on GitHub

Bug fixes

#1172·don't flush on debounced state updates·by franky47

Documentation

#1158·add a countdown to Next.js conf·by sahilkapase
#1166·fix React Router icon size in README·by franky47
#1167·add Next.js conf linktree·by franky47
#1168·fix ISR error in the GHA status on the landing page·by franky47
#1169·add more testimonials·by franky47

Other changes

#1151·bump actions/setup-node from 4.4.0 to 5.0.0·by dependabot
#1155·update to React 19.2·by franky47
#1161·wait for hydration in e2e-next/pages/push test·by franky47

Contributors

sahilkapase

v2.7.1

Published on 2025-10-06•View on GitHub

Bug fixes

#1163·make sure the state-change effect runs for multi parsers·by TkDodo

Other changes

#1157·better error handling in stats·by franky47
#1160·bail out of state updates for equal values·by TkDodo

Contributors

Alexolo and TkDodo

v2.7.0

Published on 2025-09-30•View on GitHub

Features

#1133·add memory option in the testing adapter·by franky47
#1134·multi-parsers·by TkDodo

Bug fixes

#1143·optimistic state flicker·by franky47

Documentation

#1117·Use SVG in client component for Next.js logo·by franky47
#1120·Move to nuqs.dev·by franky47
#1123·Add sitemap·by franky47
#1124·Add contributors section to landing page with GitHub API integration·by Agastya18
#1130·add AGENTS.md file·by franky47
#1131·Correct typo in README regarding Safari's rate limits·by denis-sokolov
#1132·disable autocomplete in inputs·by franky47
#1146·add trend badges for NPM downloads·by franky47
180db434·Allow crawling stats, configure change frequency·François Best

Other changes

#1121·Prevent parallel runs of pkg.pr.new within a PR·by franky47
#1126·bump vite from 7.1.3 to 7.1.5·by dependabot
#1129·vendor prettyBytes and compute tree-shaken size·by franky47
#1136·split size-limit script from build process·by miinhho

Contributors

+2

Agastya18, denis-sokolov, ffiguereo, and 7 other contributors

v2.6.0

Published on 2025-09-05•View on GitHub

Features

#1104·add warning when shallow: true is used with debounce·by I-3B
#1110·Add processUrlSearchParams middleware as adapter prop·by Multiply
#1115·add processUrlSearchParams to createSerializer·by Multiply

Documentation

#1097·Add Zod codecs community parsers·by franky47
#1103·Fix all-time stats skeletons·by franky47
#1113·use URLSearchParams.sort·by Multiply
#1116·Fix links & add framework icons·by franky47

Other changes

#1105·Securing workflows·by franky47
#1108·Use semantic-release/github 11.0.5 to handle deprecated search endpoints·by franky47
e06ca54a·Bump up size-limit client bundle threshold to 6kB·François Best

Contributors

hugotiger, I-3B, and Multiply

v2.5.2

Published on 2025-08-30•View on GitHub

Bug fixes

#1101·Referential stability for the testing adapter·by franky47

Documentation

#1088·Move stats charts from Tremor to EvilCharts·by franky47
#1093·Add feature support component·by franky47
#1096·Handle zero NPM stats (not yet available)·by franky47
f1bbb650·Parse incoming responses from NPM·François Best

Other changes

30d725f2·Fix milestone automation·François Best

Contributors

georgwittberger

v2.5.1

Published on 2025-08-25•View on GitHub

Bug fixes

#1092·Lazily create AbortController in throttle queue for CloudFlare Workers support·by franky47

Documentation

#1090·Emphasis on how to use debounce·by franky47

Other changes

#1087·Add docs typecheck & build job·by Amirmohammad-Bashiri

Contributors

Aluisio, Amirmohammad-Bashiri, Fedec96, and herkulano

v2.5.0

Published on 2025-08-22•View on GitHub

Features

#855·Key isolation·by franky47
#900·Debounce·by franky47
#953·Add support for TanStack Router·by ahmedrowaihi
#965·Add Standard Schema interface·by franky47
#1038·Add const modifier to literal parsers to auto-infer their arguments as literals·by neefrehman
#1062·Export ./package.json in exports field for Module Federation support·by AfeefRazick
#1066·defaultOptions for NuqsAdapter·by TkDodo
#1079·Add support for more global default options at the adapter level·by franky47
#1083·Allow specifying a different base type for the serializer·by franky47

Bug fixes

#996·Replace require by default conditional export field·by stefan-schubert-sbb
#1057·Type inference for defaultValue of object syntax·by TkDodo
#1063·Remove esm-only on TanStack Router export·by franky47
#1073·Handle JSON in TanStack Router·by franky47

Documentation

#787·Add inertia community adapter·by Joehoel
#976·Add blog section·by franky47
#1000·Vercel OSS program·by franky47
#1004·Add code.store & oxom as sponsors 💖·by franky47
#1005·The URL type-safety iceberg·by franky47
#1017·Fix non-null assertions·by franky47
#1021·Add Deploy on Vercel button·by franky47
#1025·Extend next-app example to include more features·by I-3B
#1027·Fix mobile navbar collapse & sticky·by franky47
#1032·Fix 500 error on Vercel ISR·by franky47
#1037·Add Aurora Scharff as a sponsor 💖·by franky47
#1041·Fix transition docs to not call parser as function·by phelma
#1043·Title is hidden behind headers on mobile·by awosky
#1051·add effect schema parser page·by ethanniser
#1052·Debounce docs edits·by franky47
#1056·Migrate docs to Fumadocs 15, Tailwind CSS v4·by fuma-nama
#1058·Fix default value for shallow in React Router disclaimer·by franky47
#1070·prevent NaN appearing in pagination example·by 87xie
#1082·Add nuqs 2.5 release blog post·by franky47
35a67025·404 error wording·François Best
fa23fcee·Fix version that introduced deprecation of throttleMs·François Best

Other changes

#985·Use React Compiler RC·by franky47
#987·bump react-router from 7.5.0 to 7.5.2·by dependabot
#990·Replace tsup with tsdown·by franky47
#991·bump vite from 6.2.6 to 6.2.7·by dependabot
#992·bump actions/setup-node from 4.3.0 to 4.4.0·by dependabot
#1011·Add RSS feed auto-discovery·by franky47
#1012·bump react-router from 7.4.0 to 7.5.2·by dependabot
#1029·Fix API stability test·by franky47
#1033·Linting PR titles·by franky47
#1035·bump next from 15.3.0 to 15.3.3 in /packages/e2e/next·by dependabot
#1046·Update NUQS-404.md·by dmytro-palaniichuk
#1065·Add TanStack Router to og:images·by franky47
#1067·Improve stats page·by franky47
#1074·Configure MDX types·by remcohaszing
#1077·Track beta versions adoption in the stats page·by franky47
#1078·Update dependencies·by franky47
#1080·Pass children as config in createElement to avoid ts-expect-error·by franky47
#1081·Reduce the bundle size·by franky47
#1086·Add publint step to CI workflow·by Amirmohammad-Bashiri
f8df1d57·Fix blog post date·François Best
d146b482·Wording·François Best
cee4e100·Update versions data·François Best
22ca0db6·Add more PR filters for VSCode·François Best
8e44040a·Filter out draft PRs·François Best

Contributors

+43

87xie, AfeefRazick, ahmedrowaihi, and 48 other contributors

v2.4.3

Published on 2025-04-16•View on GitHub

Bug fixes

#983·Multiple query reordering in Next.js pages router internal state·by franky47

Other changes

#980·Update runners to ubuntu-24.04-arm·by franky47
32c6ee8f·Revert Sentry·François Best
e12e0c24·Sentry isn't compatible with Turbopack yet·François Best

Contributors

Csszabi98

v2.4.2

Published on 2025-04-14•View on GitHub

Bug fixes

#939·Import from next/navigation.js·by franky47
#967·Prettify inferred types·by franky47
#973·Increase rate-limit factor for Next.js app router·by franky47

Documentation

#933·Add "works with" icons·by franky47
#936·add missing commas·by pnodet
#937·Add link tree for React Paris·by franky47
#946·React Paris is over 😥·by franky47
#951·Various minor edits·by franky47
#963·Waku v0.22 community adapter useRouter update ·by rmarscher
dae638da·FIx link to NUQS-303·François Best
7c43dfb8·Fix link to NUQS-404·François Best
e7d2a013·TDD·François Best

Other changes

#932·Update React Router to 7.3.0·by franky47
#949·Update dependencies·by franky47
#952·Update React to 19.1.0 & PNPM to 10.7·by franky47
#955·bump vite from 6.2.3 to 6.2.4·by dependabot
#956·bump actions/setup-node from 4.2.0 to 4.3.0·by dependabot
#957·bump actions/upload-artifact from 4.6.1 to 4.6.2·by dependabot
#959·bump @react-router/express from 7.4.0 to 7.4.1·by dependabot
#961·Add property-based testing with fast-check·by franky47
#962·bump vite from 6.2.4 to 6.2.5·by dependabot
#971·Next.js 15.3.0 with Turbopack build·by franky47
#975·bump vite from 6.2.5 to 6.2.6·by dependabot
#977·Update dependencies·by franky47
3ee873d2·Ignore PR detection on next & master·François Best
e85a138c·Cleanup·François Best
2f40ed68·Move settings to PNPM workspace file·François Best
fb6feb2d·Update version adoption data·François Best

Contributors

dubzzz, fitimbytyqi, jdpnielsen, and 3 other contributors

v2.4.1

Published on 2025-03-06•View on GitHub

Bug fixes

#923·Import React.cache only when needed·by franky47

Documentation

#922·Fix the parseAsIndex demo·by franky47
#926·Update withDefault JSDocs·by franky47
#931·Add React Paris banner·by franky47

Other changes

#928·bump actions/upload-artifact from 4.6.0 to 4.6.1·by dependabot
#929·bump pnpm/action-setup from 4.0.0 to 4.1.0·by dependabot
#930·Add vitest-package-exports·by franky47
da5ee6c8·Reduce job report verbosity·François Best
e3d6d1fd·DIsable image optimisation for all avatars·François Best
b9926ca2·Update version data·François Best
968fdae1·Add funding field in package.json·François Best

Contributors

alylim, boredland, rik-iso, and schardev

v2.4.0

Published on 2025-02-17•View on GitHub

Features

#791·Add parseAsPageIndex parser·by cenobitedk
#853·Add custom parsers testing helpers·by franky47
#861·Detect multiple contexts loaded at the same time·by franky47
#891·Full-page navigation option for shallow: false updates in React SPA·by franky47
#911·Add scroll option support for React SPA adapter·by franky47

Bug fixes

#899·Ship react-router v6/v7 .d.ts redirects on NPM·by franky47
#908·useQueryStates does not update values correctly when config changes·by maslianok
#909·Handle console.log of null values in React Devtools·by franky47

Documentation

#915·Add Unkey as sponsor 💖·by franky47
#920·Add OpenStatus as sponsor 💖·by franky47
27777684·Document PAT permissions·François Best
566d8405·Fix basic usage demo·François Best
1ec087cc·Fix query spy·François Best
3125a0c3·Update contribution guidelines (PR checklist)·François Best
c23f8382·Fix README CI/CD badge, add sponsors·François Best

Other changes

#885·Add React Router Fog of War test·by franky47
#892·Create CODE_OF_CONDUCT.md·by franky47
#894·Update deps·by franky47
#897·Move type tests away from src·by franky47
#903·Trying ubuntu-22.04-arm runners·by franky47
#917·Dynamic segments & multitenancy for Next.js pages router·by franky47
#918·Update pkg.pr.new comments·by franky47
1709d0a8·Explicit authentication with PAT for ship-it workflow·François Best
2e055c12·Setup Git for ship-it·François Best
ab980ebc·Trying to checkout with PAT·François Best
5bb78a76·Cleanup·François Best
03cc7415·Add non-regression tests for Promise referential equality·François Best
b7643223·Pool the Slack notifications for tests against Next.js releases·François Best
e11e88cb·Remove leftover file from #918·François Best

Contributors

cenobitedk, dejoma, jdpnielsen, and 4 other contributors

v2.3.2

Published on 2025-02-01•View on GitHub

Bug fixes

#858·Dynamic keys for useQueryStates·by franky47
#871·Allow useQueryStates' state updater function to return null·by franky47
#882·Conditional rendering in React Router·by franky47
#887·React Router stale values after remount·by franky47

Documentation

#753·add break word all for better ux·by rasvanjaya21
#847·Update wording for the "missing suspense boundary" guidelines·by mtlaso
#848·Add Waku community adapter·by rmarscher
8d8022cd·Remove pre-v2 callout·François Best
f6594e7f·Update React 19 support·François Best
2ee7dc58·Update tests guidelines for contributions·François Best

Other changes

#864·Test running CI on arm64 GHA runners·by franky47
#867·Update deps·by franky47
#872·Update PNPM to v10·by franky47
#878·Add test for the agnostic adapter·by franky47
#888·bump actions/setup-node from 4.1.0 to 4.2.0·by dependabot
#889·bump actions/upload-artifact from 4.5.0 to 4.6.0·by dependabot
f15516a5·Update all runners to arm64·François Best
2ac1e441·No need for Vitest here·François Best
3678adcc·Revert ARM runners·François Best
945d05f5·Back to ARM to try and solve stuck workflows·François Best
36afa136·Trying on ubuntu-latest·François Best
a0e7e7d6·And back to pinned to confirm the issue·François Best
98179a4e·Typo in image name·François Best
d60a2c57·Update sequencing·François Best
2f1220c5·Update version tracking data·François Best

Contributors

erinleigh90, mattrothenberg, mtlaso, and 4 other contributors

v2.3.1

Published on 2025-01-14•View on GitHub

Bug fixes

#840·Maintain location.state in React Router frameworks·by franky47
#841·Referential stability for the state updater function·by franky47
#854·Export UrlKeys type helper·by franky47

Documentation

4036594b·Add docs for UrlKeys·François Best

Other changes

#844·Update version range to include react-router@^6·by franky47
#849·Optimise render counts·by franky47
#851·Update deps·by franky47
#859·Try to avoid bursting e2e-next CI caching·by franky47

Contributors

alberto-htl, Dentling, dlindahl, and 4 other contributors

v2.3.0

Published on 2025-01-01•View on GitHub

Features

#785·Added react-router v7 support·by teukuamru
#800·Abstract reading from location.search in adapters interface·by franky47
#811·Shallow routing for everyone·by franky47
#818·Add loader feature ·by franky47
#824·Add UrlKeys type helper·by franky47

Bug fixes

#801·Export Nullable type for correctly inferring return type of createSerializer()·by MartinCura
#809·Preserve hash in React Router based adpaters·by franky47
#821·Support ? characters in serializer base·by franky47

Documentation

#789·Add Liminity.se as sponsor 💖·by franky47
#795·Document testing nuqs based hooks·by sebastianvitterso
#825·Fix link to options docs·by blyme
bf0e2cb8·Fix typo·Francois Best

Other changes

#796·React 19·by franky47
#797·Run GHA on Ubuntu 24.04·by franky47
#802·Move relevant e2e tests to be unit tests·by franky47
#807·Move e2e tests into shared library·by franky47
#813·Update dependencies·by franky47
#819·Enable provenance·by franky47
#828·Use a useEffect rather than useLayoutEffect·by franky47
#829·Add native HTML form test·by franky47
#833·Enable history patching by default for React Router·by franky47
#834·Reduce the amount of Slack notifications·by franky47
#835·bump actions/upload-artifact from 4.4.3 to 4.5.0·by dependabot
d5f982b1·Ship it workflow·Francois Best
990e05ad·Simplify ship-it workflow·Francois Best
2779419d·Abort if nothing to ship·Francois Best
277ffca3·Update package metadata·François Best

Contributors

+3

blyme, ealvarezk, faradaytrs, and 8 other contributors

v2.2.3

Published on 2024-11-23•View on GitHub

Bug fixes

#781·Protection against null useSearchParams in Next.js·by franky47
#783·Encode invisible ASCII control characters·by franky47

Contributors

Kamalito75, Ngocduoc763, and WKampel

v2.2.2

Published on 2024-11-20•View on GitHub

Bug fixes

#776·Update useQueryStates state cache when syncing from useSearchParams·by franky47

Contributors

geemanjs and tariwiencke

v2.2.1

Published on 2024-11-15•View on GitHub

Bug fixes

#769·Allow null value in serializer for parsers with default values·by MartinCura

Documentation

#749·Update to Fumadocs 14 / Next 15·by franky47

Other changes

#768·Update React to 19 RC1·by franky47
672aa53f·Run milestone automation in this repo's context·Francois Best

Contributors

MartinCura

v2.2.0

Published on 2024-11-14•View on GitHub

Features

#765·Add testing HOC to reduce test setup verbosity·by franky47

Bug fixes

#756·Add React 19 RC in peer dep semver range·by franky47
#762·Support for dynamic default values in useQueryStates·by franky47
#764·Make the testing adapter clear the URL queue·by franky47

Contributors

aeonzz

v2.1.2

Published on 2024-11-12•View on GitHub

Bug fixes

#747·Log an error in development if URI size of 2000 characters is exceeded.·by niklasbec
#759·Use correct keys for state sync·by franky47

Documentation

#730·Updated docs Client Components to be Wrapped in a <Suspense> Boundry·by HunainSiddiqui
#739·Add limits page to docs·by niklasbec
#743·Add Jest guidelines & ESM-only error page·by franky47
#745·Update basic-usage.mdx·by destocot
#746·Update socials: bye X, RIP Twitter, hello Bluesky·by franky47

Other changes

#732·bump actions/setup-node from 4.0.4 to 4.1.0·by dependabot
#733·bump actions/upload-artifact from 4.4.0 to 4.4.3·by dependabot
#734·bump actions/checkout from 4.2.0 to 4.2.2·by dependabot
#735·Add milestone automation·by franky47
#744·Split e2e test environments·by franky47

Contributors

+5

delinuxist, destocot, frontendparham, and 10 other contributors

v2.1.1

Published on 2024-10-31•View on GitHub

Bug fixes

#729·wrap setOptimisticSearchParams in startTransition·by aryasaatvik

Contributors

aryasaatvik

v2.1.0

Published on 2024-10-30•View on GitHub

Features

#707·Add parseAsISODate·by tylersayshi
#710·Export the SearchParams type in both client & server bundles·by franky47
#712·Export OnUrlUpdateFunction type for Vitest v2·by franky47
#720·Add urlKeys & clearOnDefault support for serializer·by franky47
#725·Add support for urlKeys in cache·by franky47

Bug fixes

#718·Use optimistic search params in app router·by franky47

Documentation

#716·Update tips-tricks.mdx·by gsaandy
0ddd7d09·Add Vercel to the sponsors list·Francois Best
949297da·Fix wordmark on Safari·Francois Best
89f2b021·Fix UTC date inputs·Francois Best

Other changes

adbcf708·Use a workflow dispatch to force CI·Francois Best
4c2b46a6·Fix labelled logic for pkg.pr.new·Francois Best

Contributors

anaclumos, bryanjtc, gdaybrice, and 3 other contributors

v2.0.4

Published on 2024-10-24•View on GitHub

Bug fixes

#703·Read queued updates when initialising state·by franky47

Documentation

#704·Fix date inputs on Chrome·by mehm8128

Other changes

13808b8e·Add a way to move master from my phone·Francois Best
60cb4d88·Revert "chore: Add a way to move master from my phone"·Francois Best

Contributors

firatciftci and mehm8128

v2.0.3

Published on 2024-10-23•View on GitHub

Bug fixes

#701·Add stub CJS exports for old ESLint plugins·by franky47

Contributors

acocheo and GBvanDam

v2.0.2

Published on 2024-10-23•View on GitHub

Bug fixes

#700·Make clearOnDefault: true by default·by franky47

v2.0.1

Published on 2024-10-22•View on GitHub

Bug fixes

#694·Add back the .js extension to the pages router adapter·by franky47
#697·Mark framework packages as optional peer dependencies·by franky47

Contributors

nezouse, rettgerst, and tiagoskaneta

v2.0.0

Published on 2024-10-22•View on GitHub

nuqs is now extensible to all React frameworks, not just Next.js.

Announcement post
Migrations docs

Features

a1013704·Introducing adapters for other frameworks·Francois Best
e603a4d2·Add vanilla React adapter sandbox·Francois Best
ac95384d·Provide specialised adapters for both Next.js routers·Francois Best
4ae6c814·Add Remix adapter·Francois Best
cb30a20c·Add React Router adapter·Francois Best
6618f455·Render pretty URLs in other adapters·Francois Best
a56aa110·Add adapter for One·Francois Best
3ef698f8·Add custom adapters API (unstable)·Francois Best

Bug fixes

53a37d46·parseAsJson now requires a runtime validation function·Francois Best

Documentation

#666·Update to latest fumadocs·by franky47
#686·Add community parsers·by franky47
#687·v2 announcement blog post·by franky47

Other changes

#633·Pure internal state init function·by franky47
#673·Use Node.js 22 (preparing for LTS update)·by franky47
#675·Return to react19rc·by franky47
#678·Install Next.js versions to both e2e & nuqs·by franky47
408fd382·ESM only (drop CJS support)·Francois Best
8d2ba249·Remove deprecated APIs·Francois Best
4616a7b0·Drop mirrorring to next-usequerystate·Francois Best
b6bdc661·Rename nuqs/parsers to nuqs/server·Francois Best
9665a93d·Update list of supported versions·Francois Best
c509a996·Update minimum supported Next.js version·Francois Best
8950bc89·Move urlKeys into the UseQueryStatesOptions type·Francois Best

v1.20.0

Published on 2024-10-07•View on GitHub

Features

#657·allow null to clear all param values from base·by neefrehman
#671·Allow remapping keys in useQueryStates·by franky47

Documentation

#654·Don't optimise dependents' avatars·by franky47

Other changes

#656·Fix: Run pkg.pr.new only if there are changes·by chbg
#659·Refactor: Split pkg.pr.new into distinct check and deploy jobs·by chbg
#660·Bump actions/checkout from 4.1.7 to 4.2.0·by dependabot
#661·Bump actions/setup-node from 4.0.3 to 4.0.4·by dependabot
#664·Annotate deployment job·by franky47
#668·Drop npm-run-all·by franky47
a0cc24e5·Add e2e template page·Francois Best

Contributors

chbg and neefrehman

v1.19.3

Published on 2024-09-26•View on GitHub

Bug fixes

#647·Allow serializers to operate on derived UrlSearchParams classes·by neefrehman
#652·Handle Promises for the searchParams page prop·by franky47

Documentation

#645·Update batching.mdx·by weisisheng

Other changes

#649·Run CI when contributors add commits to their PRs·by franky47
#650·Prevent PRs targetting the master branch·by franky47

Contributors

neefrehman and weisisheng

v1.19.2

Published on 2024-09-23•View on GitHub

Bug fixes

#642·Serialization of default values in createSerializer·by hugotiger

Contributors

hugotiger

v1.19.1

Published on 2024-09-05•View on GitHub

Bug fixes

#631·Cache the query string in useQueryStates·by franky47

Other changes

#628·Add SVG wordmark·by franky47
e65560b5·Fix s color in wordmark·Francois Best

Contributors

firatciftci

v1.19.0

Published on 2024-09-02•View on GitHub

Features

#622·Allow clearing all search params managed by useQueryStates·by franky47

Bug fixes

#617·Ensure referential stability for values·by franky47
#621·Allow parser-level options in useQueryStates·by franky47

Other changes

#619·Bump actions/upload-artifact from 4.3.4 to 4.4.0·by dependabot
#624·Lint monorepo with Sherif·by franky47
#625·Add pkg.pr.new to preview PRs outside of NPM·by franky47
#626·Update dependencies·by franky47

Contributors

dev-aly3n

v1.18.0

Published on 2024-08-30•View on GitHub

Features

#578·Add parser type inference helpers·by franky47

Documentation

#614·Add og:images·by franky47
#615·Add @lindesvard as sponsor·by franky47
#616·Add tic tac toe example·by franky47

Other changes

#601·Add deferred pattern test·by franky47
#605·Add href generation test using serializer + useQueryStates·by franky47
285f0457·Make tic tac toe empty cells easier to share·Francois Best
4a0e1513·Replace all·Francois Best
a00215f8·Update versions data·Francois Best

v1.17.8

Published on 2024-08-08•View on GitHub

Bug fixes

#600·Encode special characters in keys·by franky47

Contributors

lecbyjak

v1.17.7

Published on 2024-08-05•View on GitHub

Bug fixes

#592·Move debug localStorage detection inline·by franky47

Documentation

#596·Update sponsors section - thanks @pontusab 🫶·by franky47

Other changes

#590·Check Prettier formatting in CI·by franky47
#593·Bump actions/setup-node from 4.0.2 to 4.0.3·by dependabot
#594·Bump actions/upload-artifact from 4.3.3 to 4.3.4·by dependabot

v1.17.6

Published on 2024-07-25•View on GitHub

Bug fixes

#588·localStorage availability check update·by iuriizaporozhets

Other changes

5ea49018·Update quotes·Francois Best

Contributors

iuriizaporozhets

v1.17.5

Published on 2024-07-20•View on GitHub

Bug fixes

#580·Shallow equality check on cache parsing input·by franky47

Other changes

#562·Smarter CI setup·by franky47
#563·Use React 19 RC·by franky47
#568·Bump pnpm/action-setup from 3.0.0 to 4.0.0·by dependabot
#577·Update turborepo to v2·by franky47
#579·Bump actions/checkout from 4.1.4 to 4.1.7·by dependabot

v1.17.4

Published on 2024-05-14•View on GitHub

Bug fixes

#560·Harden debug reading of localStorage·by franky47

Other changes

e29ab795·Update versions data·Francois Best

v1.17.3

Published on 2024-05-14•View on GitHub

Bug fixes

#557·don't fail parse if called again with identical input·by rikbrown

Other changes

#559·Pin pnpm version in root package.json·by franky47

Contributors

rikbrown

v1.17.2

Published on 2024-05-06•View on GitHub

Bug fixes

9912eef8·Don't rely on URL for initial state·Francois Best

Documentation

#535·Use unstable_cache for dependents caching·by franky47
#540·Fix SSR "source on GitHub"·by franky47

Other changes

#523·Update all pnpm dependencies (2024-03-18)·by depfu
#529·Update all pnpm dependencies (2024-03-25)·by depfu
#533·Bump actions/checkout from 4.1.1 to 4.1.2·by dependabot
#534·Update all pnpm dependencies (2024-04-01)·by depfu
#538·Update all pnpm dependencies (2024-04-08)·by depfu
#541·Update all pnpm dependencies (2024-04-15)·by depfu
#545·Update all pnpm dependencies (2024-04-22)·by depfu
#549·Update all pnpm dependencies (2024-04-29)·by depfu
#550·Bump actions/checkout from 4.1.2 to 4.1.4·by dependabot
#551·Bump actions/upload-artifact from 4.3.1 to 4.3.3·by dependabot

v1.17.1

Published on 2024-03-02•View on GitHub

Bug fixes

#504·Equality check for non-primitives in clearOnDefault·by franky47

Other changes

#500·Add failing test case for issue 498·by franky47
#502·Analyse Next.js releases for app router changes·by franky47
#503·Add API route for dependents·by franky47
#511·Bump actions/upload-artifact from 4.3.0 to 4.3.1·by dependabot
#512·Bump actions/setup-node from 4.0.1 to 4.0.2·by dependabot
#513·Bump pnpm/action-setup from 2.4.0 to 3.0.0·by dependabot

Contributors

Kavan72

v1.17.0

Published on 2024-02-13•View on GitHub

Features

#493·Add "clear on default" option·by franky47

Documentation

#485·Split readme into pages·by franky47

Other changes

#472·Update all pnpm dependencies (2024-02-05)·by depfu
#486·Alias nuqs/server to nuqs/parsers·by franky47
#501·Fix anchor nav in docs breaking interactive demos·by franky47

Contributors

ctian1, oliverstreissi, rwieruch, and 2 other contributors

v1.16.1

Published on 2024-02-01•View on GitHub

Bug fixes

50da1486·Sync with useSearchParams in 14.1.0·François Best

Other changes

#483·Bump actions/upload-artifact from 4.0.0 to 4.3.0·by dependabot

v1.16.0

Published on 2024-01-28•View on GitHub

Features

#475·Add serializer helper·by franky47

Documentation

#467·Add quotes·by franky47
#469·Add footer·by franky47

Contributors

oroalej

v1.15.4

Published on 2024-01-19•View on GitHub

Bug fixes

#465·Mark global next internal as optional·by franky47

Other changes

f9c89d34·Fix e2e tests (MSwCSRB)·Francois Best

Contributors

bestLessons and Meemaw

v1.15.3

Published on 2024-01-17•View on GitHub

Bug fixes

#457·WHS stabilisation·by franky47
#461·Regression in mounting components·by franky47

See more releases on GitHub

About

About the nuqs library

Migration guide to v2

How to update your code to use nuqs@2.0.0

On this page

v2.9.0 v2.8.9 v2.8.8 v2.8.7 v2.8.6 v2.8.5 v2.8.4 v2.8.3 v2.8.2 v2.8.1 v2.8.0 v2.7.3 v2.7.2 v2.7.1 v2.7.0 v2.6.0 v2.5.2 v2.5.1 v2.5.0 v2.4.3 v2.4.2 v2.4.1 v2.4.0 v2.3.2 v2.3.1 v2.3.0 v2.2.3 v2.2.2 v2.2.1 v2.2.0 v2.1.2 v2.1.1 v2.1.0 v2.0.4 v2.0.3 v2.0.2 v2.0.1 v2.0.0 v1.20.0 v1.19.3 v1.19.2 v1.19.1 v1.19.0 v1.18.0 v1.17.8 v1.17.7 v1.17.6 v1.17.5 v1.17.4 v1.17.3 v1.17.2 v1.17.1 v1.17.0 v1.16.1 v1.16.0 v1.15.4 v1.15.3

Sponsored by

Stay up to date on Next.js
A weekly newsletter to keep up with what's happening in the ecosystem.
shadcnstudio.comshadcn blocks & templates
Accelerate your project development with ready-to-use, and fully customizable shadcn ui Components, Blocks, UI Kits, Boilerplates, Templates and Themes with AI Tools 🪄.
1771 Technologies
Ship faster with LyteNyte Grid. The fastest React data grid ever built on the modern web.