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.
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.
- History Entry Replacements - Controls whether URL state updates replace or push browser history entries for back-button navigation.
- Standard Schema Validators - Converts search param definitions into Standard Schema objects for validating external data.
- Transition Loading States - Integrates with React's useTransition to show pending UI while server components re-render.
- History Entry Replacements - Controls whether URL state updates replace or push browser history entries for back-button navigation.
- URL Key Remappers - Remaps long internal variable names to short URL query string keys for cleaner URLs.
- Realtime Update Throttles - Queues and throttles URL updates to comply with browser rate limits, keeping the UI responsive.
- URL Update Queues - Queues and throttles URL updates to comply with browser rate limits while keeping state responsive.
- History Entry Replacements - Controls whether URL state updates replace or push browser history entries for back-button navigation.
- Server - Performs shallow client-side updates by default with opt-in server notification and throttle control.
- Loading State Indicators - Integrates with React's useTransition to display loading indicators while server-side state updates are in progress.
- Loading State Indicators - Integrates with React's useTransition to show loading indicators while the server re-renders.
- History Entry Replacements - Controls whether URL state updates replace or push browser history entries for back-button navigation.
- URL Update Assertions - Captures URL changes triggered by component actions and exposes new search parameters for test verification.
- Framework Adapters - Wraps URL state hooks to work across different React frameworks and routing libraries.
- Server Re-rendering Triggers - Triggers full server round-trips when URL query parameters change to re-render page content.
- History Entry Replacements - Controls whether URL state updates replace or push browser history entries for back-button navigation.
- Query String Construction - Generates query strings from state values for use in links and canonical URLs.
- Server Re-rendering Controls - Opts out of client-only updates to notify the server when query parameters change, enabling server-side rendering.
- Debounced State Updates - Delays URL updates until state changes settle, useful for high-frequency inputs like search fields.
- External Component Bridges - Bridges typed routing schemas with external state components for cross-system URL parameter validation.
- TanStack Router Validators - Provides TanStack Router integration with Standard Schema validators for type-safe URL search parameter validation.
- Query Parameter Resets - Resets every search parameter controlled by a hook to its default by passing null to the updater.
