0
# nuqs
1
2
nuqs is a type-safe state management library for Next.js that synchronizes React component state with URL query parameters. It provides React hooks that work like `useState` but store values in the URL query string, enabling shareable URLs and maintaining state across page refreshes.
3
4
## Package Information
5
6
- **Package Name**: nuqs
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install nuqs`
10
11
## Core Imports
12
13
```typescript
14
import { useQueryState, useQueryStates, parseAsInteger } from "nuqs";
15
```
16
17
For server-side usage:
18
19
```typescript
20
import { createSearchParamsCache, parseAsString } from "nuqs/server";
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { useQueryState, parseAsInteger } from "nuqs";
27
28
export default function SearchPage() {
29
const [search, setSearch] = useQueryState('q');
30
const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
31
32
return (
33
<div>
34
<input
35
value={search || ''}
36
onChange={(e) => setSearch(e.target.value)}
37
placeholder="Search..."
38
/>
39
<p>Current page: {page}</p>
40
<button onClick={() => setPage(page + 1)}>Next Page</button>
41
</div>
42
);
43
}
44
```
45
46
## Architecture
47
48
nuqs is built around several key components:
49
50
- **Query State Hooks**: `useQueryState` and `useQueryStates` provide React state management synchronized with URL query parameters
51
- **Parser System**: Type-safe parsers for converting between query strings and typed values (integers, booleans, dates, arrays, etc.)
52
- **Server-Side Cache**: Server components can access and parse query parameters with `createSearchParamsCache`
53
- **Synchronization Engine**: Cross-hook synchronization and external URL change detection
54
- **URL Serialization**: Utilities for generating query strings from typed values
55
56
## Capabilities
57
58
### Single Query State Management
59
60
Core hook for managing individual query parameters with type safety and default values.
61
62
```typescript { .api }
63
function useQueryState<T>(
64
key: string,
65
options?: UseQueryStateOptions<T>
66
): UseQueryStateReturn<T, undefined>;
67
68
function useQueryState<T>(
69
key: string,
70
options: UseQueryStateOptions<T> & { defaultValue: T }
71
): UseQueryStateReturn<T, T>;
72
73
interface UseQueryStateOptions<T> extends Parser<T>, Options {}
74
75
type UseQueryStateReturn<Parsed, Default> = [
76
Default extends undefined ? Parsed | null : Parsed,
77
(value: Parsed | null | ((old: Parsed | null) => Parsed | null)) => Promise<URLSearchParams>
78
];
79
```
80
81
[Query State Management](./query-states.md)
82
83
### Multiple Query States Management
84
85
Hook for managing multiple related query parameters as a single state object.
86
87
```typescript { .api }
88
function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
89
keyMap: KeyMap,
90
options?: UseQueryStatesOptions
91
): UseQueryStatesReturn<KeyMap>;
92
93
type UseQueryStatesKeysMap<Map = any> = {
94
[Key in keyof Map]: KeyMapValue<Map[Key]>;
95
};
96
97
type UseQueryStatesReturn<T extends UseQueryStatesKeysMap> = [
98
Values<T>,
99
SetValues<T>
100
];
101
```
102
103
[Multiple Query States](./query-states.md)
104
105
### Type-Safe Parsers
106
107
Built-in parsers for common data types with fluent API for configuration and default values.
108
109
```typescript { .api }
110
const parseAsString: ParserBuilder<string>;
111
const parseAsInteger: ParserBuilder<number>;
112
const parseAsHex: ParserBuilder<number>;
113
const parseAsFloat: ParserBuilder<number>;
114
const parseAsBoolean: ParserBuilder<boolean>;
115
const parseAsTimestamp: ParserBuilder<Date>;
116
const parseAsIsoDateTime: ParserBuilder<Date>;
117
118
function parseAsStringEnum<Enum extends string>(validValues: Enum[]): ParserBuilder<Enum>;
119
function parseAsStringLiteral<Literal extends string>(validValues: readonly Literal[]): ParserBuilder<Literal>;
120
function parseAsNumberLiteral<Literal extends number>(validValues: readonly Literal[]): ParserBuilder<Literal>;
121
function parseAsArrayOf<ItemType>(itemParser: Parser<ItemType>, separator?: string): ParserBuilder<ItemType[]>;
122
function parseAsJson<T>(parser?: (value: unknown) => T): ParserBuilder<T>;
123
124
interface ParserBuilder<T> extends Required<Parser<T>> {
125
withDefault(defaultValue: NonNullable<T>): ParserBuilder<T> & { defaultValue: NonNullable<T> };
126
withOptions(options: Options): ParserBuilder<T>;
127
}
128
```
129
130
[Type-Safe Parsers](./parsers.md)
131
132
### Server-Side Cache
133
134
Server-side utilities for accessing and parsing query parameters in React Server Components.
135
136
```typescript { .api }
137
function createSearchParamsCache<Parsers extends Record<string, ParserBuilder<any>>>(
138
parsers: Parsers
139
): {
140
parse(searchParams: SearchParams): ParsedSearchParams;
141
get<Key extends keyof Parsers>(key: Key): ParsedSearchParams[Key];
142
all(): ParsedSearchParams;
143
};
144
145
type SearchParams = Record<string, string | string[] | undefined>;
146
```
147
148
[Server-Side Cache](./server-cache.md)
149
150
### URL Serialization
151
152
Utilities for generating query strings from typed values using parser configuration.
153
154
```typescript { .api }
155
function createSerializer<Parsers extends Record<string, ParserBuilder<any>>>(
156
parsers: Parsers
157
): SerializerFunction<Parsers>;
158
159
interface SerializerFunction<Parsers extends Record<string, ParserBuilder<any>>> {
160
(values: Values<Parsers>): string;
161
(base: string | URLSearchParams | URL, values: Values<Parsers> | null): string;
162
}
163
164
type Values<Parsers extends Record<string, ParserBuilder<any>>> = Partial<{
165
[K in keyof Parsers]?: ExtractParserType<Parsers[K]>;
166
}>;
167
168
type ExtractParserType<Parser> = Parser extends ParserBuilder<any>
169
? ReturnType<Parser['parseServerSide']>
170
: never;
171
```
172
173
[URL Serialization](./serialization.md)
174
175
### Query Update Notifications (Deprecated)
176
177
Deprecated synchronization utility for listening to URL query changes.
178
179
```typescript { .api }
180
/**
181
* @deprecated Since Next.js introduced shallow routing in 14.0.3, this method is no longer needed.
182
* This method will be removed in nuqs@2.0.0.
183
*/
184
function subscribeToQueryUpdates(
185
callback: (args: QueryUpdateNotificationArgs) => void
186
): () => void;
187
188
type QueryUpdateSource = 'internal' | 'external';
189
interface QueryUpdateNotificationArgs {
190
search: URLSearchParams;
191
source: QueryUpdateSource;
192
}
193
```
194
195
### Legacy APIs (Deprecated)
196
197
Deprecated APIs maintained for backward compatibility.
198
199
```typescript { .api }
200
/**
201
* @deprecated renamed to Parser
202
*/
203
type Serializers<T> = Parser<T>;
204
205
/**
206
* @deprecated renamed to ParserBuilder. You should probably use createParser instead.
207
*/
208
type SerializersWithDefaultFactory<T> = ParserBuilder<T>;
209
210
/**
211
* @deprecated use individual parseAsXyz imports instead.
212
*/
213
const queryTypes: {
214
readonly string: ParserBuilder<string>;
215
readonly integer: ParserBuilder<number>;
216
readonly float: ParserBuilder<number>;
217
readonly boolean: ParserBuilder<boolean>;
218
readonly timestamp: ParserBuilder<Date>;
219
readonly isoDateTime: ParserBuilder<Date>;
220
readonly stringEnum: typeof parseAsStringEnum;
221
readonly json: typeof parseAsJson;
222
readonly array: typeof parseAsArrayOf;
223
};
224
225
/**
226
* @deprecated use individual parseAsXyz imports instead
227
*/
228
type QueryTypeMap = typeof queryTypes;
229
```
230
231
## Core Types
232
233
```typescript { .api }
234
interface Parser<T> {
235
/** Convert a query string value into a state value */
236
parse: (value: string) => T | null;
237
/** Render the state value into a query string value */
238
serialize?: (value: T) => string;
239
/** Check if two state values are equal */
240
eq?: (a: T, b: T) => boolean;
241
}
242
243
interface Options<Shallow = unknown> {
244
/** How the query update affects page history (defaults to 'replace') */
245
history?: 'replace' | 'push';
246
/** Scroll to top after a query state update (defaults to false) */
247
scroll?: boolean;
248
/** Shallow mode keeps updates client-side only (defaults to true) */
249
shallow?: Extract<Shallow | boolean, boolean>;
250
/** Maximum time (ms) between URL query string updates (defaults to 50ms) */
251
throttleMs?: number;
252
/** React transition function for observing Server Component loading states */
253
startTransition?: TransitionStartFunction;
254
/** Clear key-value pair from URL when setting state to default value */
255
clearOnDefault?: boolean;
256
}
257
258
type HistoryOptions = 'replace' | 'push';
259
260
type TransitionStartFunction = (callback: () => void) => void;
261
262
type Nullable<T> = {
263
[K in keyof T]: T[K] | null;
264
};
265
```