Skip to content
Get packs

nuqs

A React hook that keeps component state in the URL query string, like useState but in the address bar.

GitHub Download v2.10.2
Stars
10.9k
Forks
297
Licence
MIT
Language
TypeScript
Last update
4 days ago
Type
Library

What it is

nuqs is a TypeScript library for React apps that stores state in the URL's query string instead of in memory. You use it much like React's useState: you get a value and a setter, but the value appears in the address (for example ?name=foo), so it survives page reloads and can be shared as a link. It provides adapters for Next.js, plain React, Remix, React Router and TanStack Router.

  • Keep a table's sort column and page number in the URL so the view can be shared
  • Sync a search box's text to ?q= so the Back button restores previous searches
  • Store multiple related filters together with useQueryStates
  • Read typed search params in nested server components via the server cache

Great for

  • React developers building filterable, searchable or paginated pages
  • Teams using Next.js (app or pages router) who want type-safe search params
  • Apps where users should be able to bookmark or share a view's state
  • Projects already on React Router v6+/v7/v8 or Remix who need URL-synced state

Not ideal for

  • Projects that do not use React or a supported framework, since the library and adapters are React-specific
  • Sensitive data, because anything stored in the query string is visible in the URL and browser history
  • Projects on Next.js older than 14.2 without pinning to nuqs v1, as the README says the adapter code needs 14.2 or later
Step-by-step guide: how to use nuqsInstall, first run, examples, tips and FAQs
nuqs alternativesnuqs vs Zustandnuqs vs TanStack Router

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js and a package manager such as npm, pnpm, yarn, bun or deno · A React project using one of the supported frameworks or routers

    Install with npm

    npm install nuqs

    Install with pnpm

    pnpm add nuqs
  2. 2

    Run it

    • Install the package with npm install nuqs in your project
    • Wrap your app tree in the NuqsAdapter that matches your framework, such as nuqs/adapters/react for plain React or nuqs/adapters/next/app for Next.js app router
    • In a client component, import useQueryState from nuqs and call it with a key name
    • Set the value with the returned setter and check that the URL query string updates
  3. 3

    Get the most out of it

    • Use useQueryStates to manage several related query parameters together
    • Create custom parsers to handle custom types or prettier URLs
    • Choose history append mode if you want the Back button to step through state changes
    • Enable shallow: false if you need server components to be notified of URL updates
    • Use useTransition to show loading states while server updates run

Downloads

Source code (.zip)next branch · straight from GitHubRelease v2.10.2Release notes and sourceOfficial website & docsnuqs.dev

Strengths

  • Simple model: the URL becomes the source of truth for the state
  • Built-in parsers for types such as integers, floats, booleans and Dates, plus support for custom parsers
  • Supports several frameworks and routers through adapters, with an MIT license

Trade-offs

  • Only works in client components in Next.js, and the README notes TanStack Router support is experimental and does not cover TanStack Start
  • Values in the URL are visible and user-editable, so it is unsuitable for secrets
  • Requires wrapping your app in a framework-specific adapter, which adds setup that differs by router

How it compares

ProjectStarsTypeLevelUpdatedBest for
nuqs (this)10.9kLibrarybeginner4 days agoReact developers building filterable, searchable or paginated pages
zustand58.9kLibrarybeginner15 days agoReact developers who want simpler shared state than Redux
xstate30.4kLibraryintermediate4 days agoFrontend developers managing complex UI flows with many interacting states
vuex28.3kLibraryintermediate2.1 years agoTeams maintaining an existing Vue app that already uses Vuex
router15.3kLibraryintermediate4 days agoReact developers who want type-checked routes and URL parameters
bloc12.5kLibraryintermediate4 days agoFlutter developers who want to separate UI code from business logic

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.