nuqs

nuqs.47ng.com

Type-safe URL search params state manager for React and Next.js apps.

Overview

nuqs is a React library that brings type-safe state management to URL query parameters. It provides a familiar `useState`-like API that automatically syncs state with the URL, making it easy to build shareable, bookmarkable interfaces without prop drilling.

The library supports multiple React frameworks including Next.js (both app and pages routers), Remix, React Router, TanStack Router, and plain React SPAs. It includes built-in parsers and serializers for common data types, history controls for back-button navigation, and server-side support for React Server Components with type safety across component boundaries.

At just 5.9kB gzipped, nuqs is lightweight yet feature-complete, with comprehensive testing against every Next.js release and a well-designed API for custom parsers and serializers.

Key features

Type-safe end-to-end state management
useState-like API synced with URL
Support for Next.js, Remix, React Router, TanStack Router
Built-in parsers and serializers
History controls and back-button support
Server-side React Server Component support
useTransition integration for loading states
Custom parser and serializer support
Only 5.9kB gzipped
Tested against every Next.js release

Pros

Familiar React API reduces learning curve
Automatic URL synchronization eliminates manual state management
Type safety across server and client components
Lightweight bundle size
Multi-framework support
Built-in utilities for common data types
Excellent test support and documentation

Cons

Requires React 18.3+ or React 19
Limited to frameworks with router support
May require refactoring existing useState-based state management

Use this if

You need type-safe URL query parameter management in React, want to build shareable interfaces with state in the URL, or are working with Next.js and need seamless server component integration.

Skip this if

You're using older versions of React (below 18.3), don't need URL-based state management, or prefer traditional state management libraries like Redux or Zustand.

Best for

Building shareable and bookmarkable React interfacesManaging filter and search state in URLsNext.js applications with app and pages routersType-safe query parameter handlingServer-side rendering with React Server ComponentsMulti-framework React projects

Alternatives

TanStack RouterReact RouterNext.js useSearchParamsZustand with URL persistenceRedux with URL sync middleware

Compare nuqs alternatives

More Library

Compare all

React Query

Data-fetching and state management library designed to handle server state in web applications.

dotenv

Zero-dependency module loading environment variables from .env files into Node.js apps.

Solidjs

JavaScript library designed for building user interfaces with a focus on declarative syntax and efficiency.

UnoCSS

Instant on-demand atomic CSS engine — flexible, fast alternative to Tailwind.