nuqs

nuqs is a TypeScript library for React that stores UI state directly in the URL's query string rather than in memory. A URL query string is the part after the question mark in a web address, like the word "search" in something like "example.com/results?search=hello". Normally, React developers use a built-in tool called useState to hold values like form fields or filter selections in memory, but those values disappear if you refresh the page or share the link. nuqs keeps those values in the URL instead, making them shareable and persistent across page loads.

The library works similarly to React's useState in terms of how you write code: you call a hook, get back a current value and a function to update it, and the URL reflects the change automatically. It includes built-in converters for common types like integers, floating point numbers, booleans, dates, arrays, and JSON objects, so you do not have to manually convert URL strings into the types your code actually needs.

The library supports several popular React frameworks including Next.js (both its older pages-based router and the newer app router), plain single-page React apps, Remix, React Router, and TanStack Router. Each framework needs a small wrapper added at the top of the component tree to handle the differences in how each one reads and writes URLs.

Other features include the ability to treat URL updates like browser history entries, so users can press the back button to undo a state change, and a way for server-rendered components to read the same query parameters in a type-safe way. Full documentation lives at nuqs.dev.