0
# Location Strategies
1

2
Different location hook implementations for various routing strategies including browser history, hash-based routing, and memory-based routing for testing and SSR.
3

4
## Capabilities
5

6
### Browser Location Hook
7

8
Default location strategy using the browser's History API for standard web application routing with full URL path support.
9

10
```typescript { .api }
11
/**
12
 * Default browser location hook using History API
13
 * @param options - Configuration options for SSR and path handling
14
 * @returns Tuple of [currentPath, navigateFunction]
15
 */
16
function useBrowserLocation(options?: { ssrPath?: Path }): [Path, typeof navigate];
17

18
type BrowserLocationHook = (options?: { ssrPath?: Path }) => [Path, typeof navigate];
19

20
/**
21
 * Navigate to a new location using History API
22
 * @param to - Target path or URL
23
 * @param options - Navigation options including replace and state
24
 */
25
function navigate<S = any>(
26
  to: string | URL,
27
  options?: { replace?: boolean; state?: S }
28
): void;
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { Router } from "wouter";
35
import { useBrowserLocation } from "wouter/use-browser-location";
36

37
// Default browser routing (this is the default)
38
function App() {
39
  return (
40
    <Router>
41
      <Routes />
42
    </Router>
43
  );
44
}
45

46
// Explicit browser location hook
47
function AppWithCustomHook() {
48
  return (
49
    <Router hook={useBrowserLocation}>
50
      <Routes />
51
    </Router>
52
  );
53
}
54

55
// Direct navigation
56
import { navigate } from "wouter/use-browser-location";
57

58
function CustomButton() {
59
  const handleClick = () => {
60
    navigate("/dashboard", { 
61
      replace: false,
62
      state: { from: "button" }
63
    });
64
  };
65
  
66
  return <button onClick={handleClick}>Go to Dashboard</button>;
67
}
68
```
69

70
### Browser Location Utilities
71

72
Additional hooks for fine-grained access to browser location properties, available from the `wouter/use-browser-location` import.
73

74
```typescript { .api }
75
/**
76
 * Hook for accessing URL pathname
77
 * @param options - SSR path options
78
 * @returns Current pathname
79
 */
80
function usePathname(options?: { ssrPath?: Path }): Path;
81

82
/**
83
 * Hook for accessing URL search parameters
84
 * @param options - SSR search options
85
 * @returns Current search string
86
 */
87
function useSearch(options?: { ssrSearch?: SearchString }): SearchString;
88

89
/**
90
 * Hook for accessing browser history state
91
 * @returns Current history state
92
 */
93
function useHistoryState<T = any>(): T;
94

95
/**
96
 * Generic hook for subscribing to location property changes
97
 * @param fn - Function to get current value
98
 * @param ssrFn - Function to get SSR value
99
 * @returns Current property value
100
 */
101
function useLocationProperty<S extends Primitive>(
102
  fn: () => S,
103
  ssrFn?: () => S
104
): S;
105

106
type BrowserSearchHook = (options?: { ssrSearch?: SearchString }) => SearchString;
107
```
108

109
**Import Pattern:**
110

111
```typescript
112
import { 
113
  usePathname, 
114
  useSearch, 
115
  useHistoryState,
116
  useLocationProperty,
117
  navigate
118
} from "wouter/use-browser-location";
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
import { 
125
  usePathname, 
126
  useSearch, 
127
  useHistoryState,
128
  useLocationProperty 
129
} from "wouter/use-browser-location";
130

131
function LocationDetails() {
132
  const pathname = usePathname();
133
  const search = useSearch();
134
  const historyState = useHistoryState();
135
  
136
  return (
137
    <div>
138
      <p>Pathname: {pathname}</p>
139
      <p>Search: {search}</p>
140
      <p>State: {JSON.stringify(historyState)}</p>
141
    </div>
142
  );
143
}
144

145
function CustomLocationHook() {
146
  // Custom property tracking
147
  const hash = useLocationProperty(
148
    () => location.hash,
149
    () => "" // SSR fallback
150
  );
151
  
152
  return <div>Hash: {hash}</div>;
153
}
154
```
155

156
### Hash Location Hook
157

158
Location strategy using URL hash for routing, useful for single-page applications that need to support older browsers or static hosting.
159

160
```typescript { .api }
161
/**
162
 * Hash-based location hook using URL hash for routing
163
 * @param options - Configuration options including SSR path
164
 * @returns Tuple of [currentPath, navigateFunction]
165
 */
166
function useHashLocation(options?: { ssrPath?: Path }): [Path, typeof navigate];
167

168
/**
169
 * Navigate using hash-based routing
170
 * @param to - Target path (will be prefixed with #/)
171
 * @param options - Navigation options
172
 */
173
function navigate<S = any>(
174
  to: Path,
175
  options?: { state?: S; replace?: boolean }
176
): void;
177
```
178

179
The hash location hook also provides a custom href formatter:
180

181
```typescript { .api }
182
/** HREF formatter for hash routing - prefixes paths with # */
183
useHashLocation.hrefs: (href: string) => string;
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { Router } from "wouter";
190
import { useHashLocation } from "wouter/use-hash-location";
191

192
// Hash-based routing
193
function HashApp() {
194
  return (
195
    <Router hook={useHashLocation}>
196
      <Routes />
197
    </Router>
198
  );
199
}
200

201
// Direct hash navigation
202
import { navigate } from "wouter/use-hash-location";
203

204
function HashNavigation() {
205
  const goToPage = (page: string) => {
206
    navigate(`/${page}`, { replace: false });
207
    // URL becomes: http://example.com#/about
208
  };
209
  
210
  return (
211
    <div>
212
      <button onClick={() => goToPage("about")}>About</button>
213
      <button onClick={() => goToPage("contact")}>Contact</button>
214
    </div>
215
  );
216
}
217

218
// Custom hook usage
219
function HashLocationExample() {
220
  const [location, navigate] = useHashLocation();
221
  
222
  return (
223
    <div>
224
      <p>Hash location: {location}</p>
225
      <button onClick={() => navigate("/settings")}>
226
        Go to Settings
227
      </button>
228
    </div>
229
  );
230
}
231
```
232

233
### Memory Location Hook
234

235
In-memory location strategy for testing, server-side rendering, and controlled routing environments where browser APIs are not available.
236

237
```typescript { .api }
238
/**
239
 * Create an in-memory location hook for testing and SSR
240
 * @param options - Memory location configuration
241
 * @returns Memory location hook object with methods
242
 */
243
function memoryLocation(options?: {
244
  path?: Path;
245
  searchPath?: SearchString;
246
  static?: boolean;
247
  record?: false;
248
}): HookReturnValue;
249

250
function memoryLocation(options?: {
251
  path?: Path;
252
  searchPath?: SearchString;
253
  static?: boolean;
254
  record: true;
255
}): HookReturnValue & StubHistory;
256

257
type HookReturnValue = {
258
  /** Location hook function for use with Router */
259
  hook: BaseLocationHook;
260
  /** Search hook for query parameters */
261
  searchHook: BaseSearchHook;
262
  /** Navigation function */
263
  navigate: Navigate;
264
};
265

266
type StubHistory = { 
267
  /** Array of visited paths when record=true */
268
  history: Path[]; 
269
  /** Reset function to return to initial state */
270
  reset: () => void; 
271
};
272

273
type Navigate<S = any> = (
274
  to: Path,
275
  options?: { replace?: boolean; state?: S }
276
) => void;
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
import { Router } from "wouter";
283
import { memoryLocation } from "wouter/memory-location";
284

285
// Basic memory routing for testing
286
function TestApp() {
287
  const memoryHook = memoryLocation({ path: "/test-path" });
288
  
289
  return (
290
    <Router hook={memoryHook.hook}>
291
      <Routes />
292
    </Router>
293
  );
294
}
295

296
// Memory routing with history tracking
297
function TestWithHistory() {
298
  const memoryHook = memoryLocation({ 
299
    path: "/", 
300
    record: true 
301
  });
302
  
303
  // Navigate programmatically
304
  memoryHook.navigate("/about");
305
  memoryHook.navigate("/contact");
306
  
307
  console.log(memoryHook.history); // ["/", "/about", "/contact"]
308
  
309
  // Reset to initial state
310
  memoryHook.reset();
311
  console.log(memoryHook.history); // ["/"]
312
  
313
  return (
314
    <Router hook={memoryHook.hook}>
315
      <Routes />
316
    </Router>
317
  );
318
}
319

320
// Static routing (navigation disabled)
321
function StaticApp() {
322
  const staticHook = memoryLocation({ 
323
    path: "/static-page",
324
    static: true // Navigation calls will be ignored
325
  });
326
  
327
  return (
328
    <Router hook={staticHook.hook}>
329
      <Routes />
330
    </Router>
331
  );
332
}
333

334
// Memory routing with search parameters
335
function MemoryWithSearch() {
336
  const memoryHook = memoryLocation({
337
    path: "/search",
338
    searchPath: "q=react&page=1"
339
  });
340
  
341
  return (
342
    <Router 
343
      hook={memoryHook.hook}
344
      searchHook={memoryHook.searchHook}
345
    >
346
      <Routes />
347
    </Router>
348
  );
349
}
350

351
// Testing helper
352
function createTestRouter(initialPath = "/") {
353
  const memoryHook = memoryLocation({ 
354
    path: initialPath, 
355
    record: true 
356
  });
357
  
358
  const TestRouter = ({ children }: { children: React.ReactNode }) => (
359
    <Router hook={memoryHook.hook}>
360
      {children}
361
    </Router>
362
  );
363
  
364
  return {
365
    Router: TestRouter,
366
    navigate: memoryHook.navigate,
367
    history: memoryHook.history,
368
    reset: memoryHook.reset
369
  };
370
}
371
```
372

373
### Server-Side Rendering
374

375
All location strategies support server-side rendering with static path and search parameter configuration.
376

377
**Usage Examples:**
378

379
```typescript
380
import { Router } from "wouter";
381
import { useBrowserLocation } from "wouter/use-browser-location";
382
import { useHashLocation } from "wouter/use-hash-location";
383
import { memoryLocation } from "wouter/memory-location";
384

385
// SSR with browser location
386
function SSRBrowserApp({ ssrPath }: { ssrPath: string }) {
387
  return (
388
    <Router 
389
      hook={useBrowserLocation} 
390
      ssrPath={ssrPath}
391
      ssrSearch="param=value"
392
    >
393
      <Routes />
394
    </Router>
395
  );
396
}
397

398
// SSR with hash location
399
function SSRHashApp({ ssrPath }: { ssrPath: string }) {
400
  return (
401
    <Router 
402
      hook={useHashLocation}
403
      ssrPath={ssrPath}
404
    >
405
      <Routes />
406
    </Router>
407
  );
408
}
409

410
// SSR with memory location
411
function SSRMemoryApp({ ssrPath }: { ssrPath: string }) {
412
  const memoryHook = memoryLocation({ 
413
    path: ssrPath,
414
    static: true // Prevent navigation during SSR
415
  });
416
  
417
  return (
418
    <Router hook={memoryHook.hook}>
419
      <Routes />
420
    </Router>
421
  );
422
}
423
```
424

425
## Types
426

427
```typescript { .api }
428
type Navigate<S = any> = (
429
  to: Path,
430
  options?: { replace?: boolean; state?: S }
431
) => void;
432

433
type Primitive = string | number | bigint | boolean | null | undefined | symbol;
434

435
type HookReturnValue<H extends BaseLocationHook> = ReturnType<H>;
436

437
type HookNavigationOptions<H extends BaseLocationHook> = 
438
  EmptyInterfaceWhenAnyOrNever<
439
    NonNullable<Parameters<HookReturnValue<H>[1]>[1]>
440
  >;
441
```