Our take
Activeregular commits and releases- Activity
- 73
- Community
- 62
- Issues
- 72
- Pull requests
- 81
+21 stars in the last 30 days
- Merges more pull requests than 89% of the projects we track
- Releases more often than 81% of the projects we track
nuqs is an actively maintained, broadly adapted React library with recent releases and quick reported issue and pull-request handling, making it a credible choice for URL-backed UI state.
Good fit if
- Your React app needs query parameters to act as typed, shareable UI state.
- You use one of its supported frameworks and can install the matching adapter.
- You want MIT-licensed code, and value an active project with many contributors and recent releases.
Look elsewhere if
- Your application is not built with React or a supported React router.
- You need URL state to be validated against a domain schema automatically, since the README says parsers do not validate data.
- You need TanStack Start support, which the README says is not yet covered by its experimental TanStack Router adapter.
All health signals
| Last commit | 2026-10-13 (2 days ago) |
|---|---|
| Commits, last 90 days | 87 |
| Releases, last 12 months | 32 (latest v2.10.2, 2026-10-08) |
| Contributors | 77 (top contributor: 69% of commits) |
| Issues closed, last 90 days | 9+ (typically closed in 1 day) |
| Pull requests merged, last 90 days | 84 (typically merged in 0 days) |
| Project age | 6 years |
Checked on 2026-10-16 with the GitHub API.
Project history
Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.
Stars
10,907Forks
299Change since Nov 16, 2026: 0 stars·+1 forks
Overview
nuqs is a TypeScript library for React frameworks that treats URL query parameters as application state, offering a useState-style API while keeping values in the address bar. This helps solve the gap between transient component state and state that users should be able to share, bookmark or revisit with browser history.
It supports Next.js, plain React SPAs, Remix, React Router and TanStack Router through adapters. Built-in and custom parsers handle conversion between query strings and typed values, with server-side parsing and cache helpers for supported server-rendered use cases.
Key Features
useQueryStateanduseQueryStatesexpose one or several query parameters as React state.- Built-in parsers cover strings, numbers, booleans, dates, arrays, JSON and constrained literals; custom parsers can be composed with defaults and options.
- Choose whether updates replace the current history entry or add entries for Back-button navigation.
- Batch and throttle URL writes while updating React state immediately.
- On Next.js, opt into server notifications and use React transitions for loading states during server updates.
- Server-side loaders, search-parameter caches and serializers reuse parser definitions outside client components.
- Framework adapters and a testing adapter support integration with different routers and isolated component tests.
Use Cases
- Search and filter interfaces where users need to share or bookmark the current query and filter settings.
- Pagination, sorting or map-coordinate controls whose current values should survive a reload or be shared as a link.
- Multi-step UI controls where browser history should either collapse updates or let users step backward through them.
- Next.js applications that need typed query values in both client components and nested server components.
What you need
Detected in the repository
- Node.js (from package.json)
- Automated checks on GitHub Actions
License in plain words
MITpermissive
- Commercial use: yes
- Modify and redistribute: yes
- You must keep: the copyright and license notice
- Share your changes: no
A summary, not legal advice: the LICENSE file is what applies.
Getting Started
Install the package:
npm install nuqs
Add the adapter for your framework and use useQueryState in a client component. See the README and documentation for framework setup and parser options.
Considerations
- URL query parameters are visible and shareable, so choose carefully what state belongs there. The README also calls out canonical URLs as an SEO consideration when query strings represent local-only state.
- Parsing and serialization are not schema validation. Add validation separately when values need domain-specific constraints, and ensure serialization does not lose precision if values must round-trip accurately.
- TanStack Router support is described as experimental and does not cover TanStack Start. The README also specifies a minimum Next.js version for the documented adapters, with older versions directed to nuqs v1.
- Browser History API limits mean URL writes are throttled. This is configurable, but server updates and URL changes may not happen as frequently as internal React state updates.
- The project is active, with recent commits and releases, a wide contributor base, and reported fast issue and pull-request handling. Those activity measures are useful signals, not a guarantee of support or compatibility for a particular framework version.
Found this useful?
Share it with someone who would like nuqs.