0
# Cookie Management
1

2
Direct cookie management through the Cookies class for advanced use cases, server-side integration, and direct cookie manipulation without React components.
3

4
## Capabilities
5

6
### Cookies Class
7

8
Core cookie management class that provides direct access to cookie operations. This is the same class used internally by `useCookies` and `withCookies`.
9

10
```typescript { .api }
11
/**
12
 * Cookie management class for direct cookie operations
13
 * Re-exported from universal-cookie package
14
 */
15
class Cookies {
16
  constructor(cookies?: string | object, defaultSetOptions?: CookieSetOptions);
17
  
18
  /** Get a single cookie value by name */
19
  get(name: string, options?: CookieGetOptions): any;
20
  /** Get a single cookie value by name with type safety */
21
  get<T>(name: string, options?: CookieGetOptions): T;
22
  
23
  /** Get all cookies as an object */
24
  getAll(options?: CookieGetOptions): any;
25
  /** Get all cookies as an object with type safety */
26
  getAll<T>(options?: CookieGetOptions): T;
27
  
28
  /** Set a cookie value with optional configuration */
29
  set(name: string, value: any, options?: CookieSetOptions): void;
30
  
31
  /** Remove a cookie by name */
32
  remove(name: string, options?: CookieSetOptions): void;
33
  
34
  /** Add listener for cookie changes */
35
  addChangeListener(callback: CookieChangeListener): void;
36
  
37
  /** Remove cookie change listener */
38
  removeChangeListener(callback: CookieChangeListener): void;
39
  
40
  /** Remove all cookie change listeners */
41
  removeAllChangeListeners(): void;
42
  
43
  /** Manually refresh cookies from browser storage */
44
  update(): void;
45
}
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
import { Cookies } from 'react-cookie';
52

53
// Client-side usage
54
const cookies = new Cookies();
55

56
// Server-side usage with cookie header
57
const serverCookies = new Cookies('user=john; theme=dark; session=abc123');
58

59
// With default options
60
const cookiesWithDefaults = new Cookies(undefined, {
61
  path: '/',
62
  secure: true,
63
  sameSite: 'strict'
64
});
65
```
66

67
### Get Cookie Value
68

69
Retrieve a single cookie value by name with optional parsing control.
70

71
```typescript { .api }
72
/**
73
 * Get a single cookie value by name
74
 * @param name - Cookie name to retrieve
75
 * @param options - Options controlling how the cookie is retrieved/parsed
76
 * @returns Cookie value (parsed as object if JSON, or raw string)
77
 */
78
get(name: string, options?: CookieGetOptions): any;
79

80
interface CookieGetOptions {
81
  /** Do not parse cookie value as JSON, return raw string */
82
  doNotParse?: boolean;
83
  /** Do not update cookies when accessing (internal use) */
84
  doNotUpdate?: boolean;
85
}
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
const cookies = new Cookies();
92

93
// Basic usage - automatically parses JSON
94
cookies.set('user', { name: 'John', role: 'admin' });
95
const user = cookies.get('user'); // Returns: { name: 'John', role: 'admin' }
96

97
// Get raw string value
98
const rawUser = cookies.get('user', { doNotParse: true }); // Returns: '{"name":"John","role":"admin"}'
99

100
// Get non-existent cookie
101
const missing = cookies.get('nonexistent'); // Returns: undefined
102

103
// Get simple string cookie
104
cookies.set('theme', 'dark');
105
const theme = cookies.get('theme'); // Returns: 'dark'
106
```
107

108
### Get All Cookies
109

110
Retrieve all cookies as a key-value object.
111

112
```typescript { .api }
113
/**
114
 * Get all cookies as an object
115
 * @param options - Options controlling how cookies are retrieved/parsed
116
 * @returns Object with cookie names as keys and values as values
117
 */
118
getAll(options?: CookieGetOptions): { [name: string]: any };
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
const cookies = new Cookies();
125

126
// Set multiple cookies
127
cookies.set('username', 'john');
128
cookies.set('preferences', { theme: 'dark', lang: 'en' });
129
cookies.set('session', 'abc123');
130

131
// Get all cookies (with JSON parsing)
132
const allCookies = cookies.getAll();
133
// Returns: 
134
// {
135
//   username: 'john',
136
//   preferences: { theme: 'dark', lang: 'en' },
137
//   session: 'abc123'
138
// }
139

140
// Get all cookies as raw strings
141
const rawCookies = cookies.getAll({ doNotParse: true });
142
// Returns:
143
// {
144
//   username: 'john',
145
//   preferences: '{"theme":"dark","lang":"en"}',
146
//   session: 'abc123'
147
// }
148
```
149

150
### Set Cookie
151

152
Set a cookie value with comprehensive configuration options.
153

154
```typescript { .api }
155
/**
156
 * Set a cookie value with optional configuration
157
 * @param name - Cookie name
158
 * @param value - Cookie value (automatically JSON-stringified if object)
159
 * @param options - Cookie configuration options
160
 */
161
set(name: string, value: any, options?: CookieSetOptions): void;
162

163
interface CookieSetOptions {
164
  /** Cookie path (default: current path) */
165
  path?: string;
166
  /** Absolute expiration date */
167
  expires?: Date;
168
  /** Max age in seconds from when client receives it */
169
  maxAge?: number;
170
  /** Cookie domain (sub.domain.com or .allsubdomains.com) */
171
  domain?: string;
172
  /** HTTPS only flag */
173
  secure?: boolean;
174
  /** Server access only flag (cannot be read by JavaScript) */
175
  httpOnly?: boolean;
176
  /** SameSite policy for CSRF protection */
177
  sameSite?: boolean | 'none' | 'lax' | 'strict';
178
  /** Partitioned storage flag for third-party contexts */
179
  partitioned?: boolean;
180
}
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
const cookies = new Cookies();
187

188
// Basic usage
189
cookies.set('username', 'john');
190

191
// With expiration (24 hours from now)
192
cookies.set('session', 'abc123', {
193
  expires: new Date(Date.now() + 24 * 60 * 60 * 1000)
194
});
195

196
// With max age (1 hour in seconds)
197
cookies.set('temporary', 'data', {
198
  maxAge: 3600
199
});
200

201
// Complex object value (automatically JSON-stringified)
202
cookies.set('user_preferences', {
203
  theme: 'dark',
204
  language: 'en',
205
  notifications: true
206
});
207

208
// Security-focused cookie
209
cookies.set('auth_token', 'secret', {
210
  path: '/',
211
  secure: true,      // HTTPS only
212
  httpOnly: true,    // No JavaScript access
213
  sameSite: 'strict' // CSRF protection
214
});
215

216
// Domain-specific cookie
217
cookies.set('global_setting', 'value', {
218
  domain: '.example.com', // Available on all subdomains
219
  path: '/',
220
  maxAge: 86400 // 24 hours
221
});
222

223
// Third-party context cookie
224
cookies.set('tracking', 'id123', {
225
  sameSite: 'none',
226
  secure: true,
227
  partitioned: true
228
});
229
```
230

231
### Remove Cookie
232

233
Remove a cookie by name, requiring matching path and domain options.
234

235
```typescript { .api }
236
/**
237
 * Remove a cookie by name
238
 * @param name - Cookie name to remove
239
 * @param options - Must match path/domain used when setting the cookie
240
 */
241
remove(name: string, options?: CookieSetOptions): void;
242
```
243

244
**Usage Examples:**
245

246
```typescript
247
const cookies = new Cookies();
248

249
// Basic removal
250
cookies.remove('username');
251

252
// Remove cookie with specific path (must match original path)
253
cookies.set('data', 'value', { path: '/admin' });
254
cookies.remove('data', { path: '/admin' }); // Correct
255
cookies.remove('data'); // Won't work - path mismatch
256

257
// Remove domain-specific cookie
258
cookies.set('global', 'value', { domain: '.example.com', path: '/' });
259
cookies.remove('global', { domain: '.example.com', path: '/' });
260

261
// Remove secure cookie
262
cookies.set('secure_data', 'value', { secure: true, path: '/' });
263
cookies.remove('secure_data', { path: '/' }); // secure flag not needed for removal
264
```
265

266
### Change Listeners
267

268
Add and remove listeners for cookie changes, useful for reactive applications.
269

270
```typescript { .api }
271
/**
272
 * Add listener for cookie changes
273
 * @param callback - Function called when any cookie changes with change details
274
 */
275
addChangeListener(callback: CookieChangeListener): void;
276

277
/**
278
 * Remove cookie change listener
279
 * @param callback - Previously added callback function
280
 */
281
removeChangeListener(callback: CookieChangeListener): void;
282

283
/**
284
 * Remove all cookie change listeners
285
 */
286
removeAllChangeListeners(): void;
287
```
288

289
**Usage Examples:**
290

291
```typescript
292
const cookies = new Cookies();
293

294
// Create listener function with change details
295
const handleCookieChange = (change: CookieChangeOptions) => {
296
  console.log(`Cookie '${change.name}' changed to:`, change.value);
297
  if (change.options) {
298
    console.log('Options:', change.options);
299
  }
300
};
301

302
// Add listener
303
cookies.addChangeListener(handleCookieChange);
304

305
// Make changes - listener will be called with details
306
cookies.set('test', 'value'); // Triggers handleCookieChange with {name: 'test', value: 'value', options: {...}}
307
cookies.remove('test');       // Triggers handleCookieChange with {name: 'test', value: undefined, options: {...}}
308

309
// Remove listener when done
310
cookies.removeChangeListener(handleCookieChange);
311

312
// Multiple listeners example
313
const listener1 = (change: CookieChangeOptions) => console.log('Listener 1:', change.name);
314
const listener2 = (change: CookieChangeOptions) => console.log('Listener 2:', change.name);
315

316
cookies.addChangeListener(listener1);
317
cookies.addChangeListener(listener2);
318

319
cookies.set('trigger', 'both'); // Both listeners called
320

321
// Clean up individual listeners
322
cookies.removeChangeListener(listener1);
323
cookies.removeChangeListener(listener2);
324

325
// Or clean up all listeners at once
326
// cookies.removeAllChangeListeners();
327
```
328

329
### Manual Cookie Update
330

331
Manually refresh cookies from browser storage, typically not needed as changes are automatically detected.
332

333
```typescript { .api }
334
/**
335
 * Manually refresh cookies from browser storage
336
 * Usually not needed as cookie changes are automatically detected
337
 */
338
update(): void;
339
```
340

341
**Usage Examples:**
342

343
```typescript
344
const cookies = new Cookies();
345

346
// Force refresh from browser (rarely needed)
347
cookies.update();
348

349
// Use case: External script modified document.cookie
350
document.cookie = 'external=value; path=/';
351
cookies.update(); // Ensure cookies instance sees the change
352
console.log(cookies.get('external')); // Now returns 'value'
353
```
354

355
### Server-Side Usage
356

357
Direct usage in server environments with cookie headers.
358

359
```typescript
360
import { Cookies } from 'react-cookie';
361
import { Request, Response } from 'express';
362

363
// Express middleware example
364
function cookieMiddleware(req: Request, res: Response, next: Function) {
365
  // Parse cookies from request header
366
  const cookies = new Cookies(req.headers.cookie);
367
  
368
  // Access cookies
369
  const userId = cookies.get('user_id');
370
  const sessionToken = cookies.get('session');
371
  
372
  // Set response cookies
373
  const responseCookies = new Cookies();
374
  responseCookies.set('last_visit', new Date().toISOString());
375
  
376
  // Add to response headers
377
  const cookieHeader = responseCookies.getAll();
378
  Object.entries(cookieHeader).forEach(([name, value]) => {
379
    res.cookie(name, value);
380
  });
381
  
382
  next();
383
}
384

385
// Next.js API route example
386
export default function handler(req: NextApiRequest, res: NextApiResponse) {
387
  const cookies = new Cookies(req.headers.cookie);
388
  const userPrefs = cookies.get('preferences');
389
  
390
  // Process request based on cookie data
391
  if (userPrefs?.theme === 'dark') {
392
    // Handle dark theme logic
393
  }
394
  
395
  res.json({ message: 'Success' });
396
}
397
```
398

399
## Types
400

401
```typescript { .api }
402
interface CookieChangeOptions {
403
  name: string;
404
  value?: any;
405
  options?: CookieSetOptions;
406
}
407

408
type CookieChangeListener = (options: CookieChangeOptions) => void;
409
```