47ng

nuqs: Manage Type-Safe React State in URL Queries

nuqs is a TypeScript library for React apps that keeps UI state in URL query parameters, making it shareable and navigable. It supports Next.js, plain React, Remix, React Router and TanStack Router through adapters.

ActiveTypeScriptMITLibraryReactUrl State
Stars
10.9k
Forks
296
Stars, last 30 days
+21
Last commit
2 days ago
Contributors
77

Our take

Activeregular commits and releases

Health score

72/100

How it is scored
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 commit2026-10-13 (2 days ago)
Commits, last 90 days87
Releases, last 12 months32 (latest v2.10.2, 2026-10-08)
Contributors77 (top contributor: 69% of commits)
Issues closed, last 90 days9+ (typically closed in 1 day)
Pull requests merged, last 90 days84 (typically merged in 0 days)
Project age6 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.

Selected snapshot

Stars

10,907

Forks

299

Change 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

  • useQueryState and useQueryStates expose 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.