47ng/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.
