nuqs is a powerful, type-safe search parameters state management library for React, created by François Best. It provides a familiar API, similar to React's useState, but shifts state storage from local memory into the URL query string. This approach enables native sharing of application state via URLs, simplifies deep linking, and improves user experience by allowing browser history navigation to undo or redo state updates. The library is lightweight at only 6kB gzipped and designed to be framework-agnostic, supporting Next.js (App and Pages routers), Remix, React SPA, React Router (v6/v7), and TanStack Router.

Functionality revolves around syncing application state with URL search parameters. By defining parsers and serializers, developers can safely manage complex state types directly in the query string, ensuring consistency between server and client components. It removes the need for manual URL manipulation and complex prop drilling.

Some of the key features are:

• Type-safe: Offers end-to-end type safety between Server and Client components.
• Universal Compatibility: Supports a wide array of React frameworks including Next.js, Remix, and TanStack Router.
• Familiar API: Provides a state management experience that mimics the intuitive React useState hook.
• History Controls: Allows for fine-grained control over navigation history, including appending or replacing states.
• Server Cache: Facilitates type-safe access to search parameters in nested React Server Components without prop drilling.
• Customizable: Supports custom parsers and serializers for specific state requirements.
• Transition Support: Integrates with useTransition to provide loading states during server updates.
• Batching: Offers hooks like useQueryStates to manage multiple keys simultaneously.

Operationally, nuqs is used by importing specialized hooks such as useQueryState, paired with built-in or custom parsers for data types like integers or strings. When state is updated via these hooks, nuqs automatically updates the browser URL, keeping the application state in sync with the current path. For server-rendered applications, it efficiently handles re-renders and server updates with built-in throttle controls.

Some common use cases include:

• Filtering and Searching: Maintaining active search queries or filter categories in the URL to allow users to copy and share specific filtered views.
• Pagination: Storing the current page index in the URL so users can navigate pages and share the exact state of a paginated list.
• Tab Navigation: Persisting the active tab index or identifier in the URL to restore user selection upon refreshing the page.
• Games and Interactive UI: Managing game board states, such as in a Tic Tac Toe game, where moves can be undone or redone using the browser's back and forward buttons.