Nuqs

Nuqs

nuqs is a TypeScript library for managing React component state through the browser's URL query string. It provides a type-safe hook-based approach that synchronizes component state with the address bar, enabling shareable and bookmarkable application states. The library handles parsing and serializing URL query parameters into typed JavaScript values, supporting integers, floats, booleans, dates, and custom types with bijectivity verification.

The library distinguishes itself through its comprehensive approach to URL state management, combining batch URL updates that merge multiple parameter changes into a single history entry, with control over whether state changes replace or push to browser history. It includes server component support with caching that allows deeply nested server components to access search parameters without re-parsing, and integrates with React's useTransition to show loading states during server component re-renders. The library also provides throttled URL queuing to comply with browser rate limits while keeping hook state instantly responsive, and a Standard Schema adapter for validating external data and sharing type inference with other tools.

Beyond its core functionality, nuqs offers testing utilities that simulate URL state changes without mocking router internals, allowing unit tests for components using query state. It supports batch operations for managing multiple query parameters atomically, debouncing and throttling for performance optimization, and middleware for processing URL search parameters. The library includes features for controlling default value display, remapping variable names to short URL keys, and preventing scroll reset during URL updates. It also provides framework adapters for integration with different React frameworks and routing libraries, including support for TanStack Router validation.

Features

URL State Synchronization - Stores React component state in the browser's URL query string with type-safe parsing and serialization.

URL State Management - Stores component state in the URL query string, making it the source of truth for shareable and bookmarkable application state.

Request-Scoped Caches - Caches parsed query parameter values per page render for efficient access by deeply nested server components.

Server Re-render Triggers - Provides configurable server re-rendering triggers when URL query parameters change, with throttling support.

URL State Serialization - Generates query strings from state values using the same serialization logic as the hooks for link population.

URL Search Param Type Safety - Provides full TypeScript type safety for parsing and serializing URL query parameters.

Query State Sharing - Encapsulates parser configuration in a custom hook so multiple components share the same query string key.

URL-Driven Component Tests - Provides a testing adapter that simulates URL state changes without mocking the router, allowing unit tests for components using query state.

Server Components - Provides type-safe access to search parameters in deeply nested React Server Components.

Request-Scoped Caches - Stores parsed URL query parameters in a per-request cache for efficient access by deeply nested server components.

Search Parameter Accessors - Provides type-safe access to parsed search parameters in deeply nested server components via caching.

Search Parameter Caches - Caches parsed search parameters so deeply nested server components access them without re-parsing.

URL State Accessors - Provides type-safe access to URL search parameters in React Server Components with caching.

URL Query Parameter Batches - Provides batch URL updates that merge multiple parameter changes into a single history entry.

Atomic Query Parameter Updates - Updates several URL search parameters in a single state transition so they always stay in sync.

Multi-Parameter State Hooks - Updates and reads several URL query parameters simultaneously through a single hook, reducing boilerplate for complex state.

Related Parameter Groups - Reads and writes a group of related query parameters as a single object, keeping them synchronized.

URL-Synchronized Navigation - Controls browser history entries and triggers server re-renders when URL query parameters change.

Framework Integrations - Provides framework-specific adapters to integrate URL state management across different React frameworks.

Query String Parsers - Converts URL query string values into typed JavaScript values using built-in parsers for common types.

History Stack Controllers - Controls whether state changes replace or push to browser history for back-button navigation.

Query Parameter Parsers - Converts URL query string values into typed JavaScript values using built-in parsers for common types.

Search Parameter Accessors - Reads type-safe search parameters in nested server components without prop drilling.

Search Parameter Parsers - Parses URL query parameters on the server using a declarative schema for typed state variables in loaders and server components.

Transition-Wrapped Updates - Integrates with React's useTransition to show loading indicators during server-side URL state updates.

URL Query Type Parsers - Converts URL query strings into typed JavaScript values with built-in parsers for common types.

URL Search Param Parsers - Parses and serializes URL query parameters with TypeScript type safety and custom parser support.

URL Data Parsing - Converts query string values into typed JavaScript values using built-in parsers for integers, floats, booleans, and dates.

Transition-Wrapped Navigations - Wraps server-rendering updates in React's useTransition to show loading states during re-renders.