0
# Routing Components
1

2
Core declarative components for building navigation interfaces and defining route structure in Wouter applications.
3

4
## Capabilities
5

6
### Route Component
7

8
Declares a route pattern and renders content when the current location matches. Supports both component and render prop patterns with parameter extraction.
9

10
```typescript { .api }
11
/**
12
 * Route component for declaring route patterns and rendering content
13
 * @param props - Route configuration including path pattern and render options
14
 * @returns Rendered content if route matches, null otherwise
15
 */
16
function Route<T extends DefaultParams | undefined = undefined, RoutePath extends PathPattern = PathPattern>(
17
  props: RouteProps<T, RoutePath>
18
): ReturnType<FunctionComponent>;
19

20
interface RouteProps<T extends DefaultParams | undefined = undefined, RoutePath extends PathPattern = PathPattern> {
21
  /** Route pattern to match against - string patterns support :param syntax, RegExp patterns are supported */
22
  path?: RoutePath;
23
  /** Child content - can be React nodes or render function receiving matched parameters */
24
  children?: 
25
    | ((params: T extends DefaultParams ? T : RoutePath extends string ? StringRouteParams<RoutePath> : RegexRouteParams) => ReactNode)
26
    | ReactNode;
27
  /** Component to render when route matches - receives params as props */
28
  component?: ComponentType<RouteComponentProps<T extends DefaultParams ? T : RoutePath extends string ? StringRouteParams<RoutePath> : RegexRouteParams>>;
29
  /** Enable nested routing - route will match loosely and provide base path for nested routes */
30
  nest?: boolean;
31
}
32

33
interface RouteComponentProps<T extends DefaultParams = DefaultParams> {
34
  params: T;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { Route } from "wouter";
42

43
// Basic route with component
44
<Route path="/users" component={UserList} />
45

46
// Route with parameters using render prop
47
<Route path="/users/:id">
48
  {(params) => <UserDetail userId={params.id} />}
49
</Route>
50

51
// Route with children
52
<Route path="/dashboard">
53
  <DashboardContent />
54
</Route>
55

56
// Nested route
57
<Route path="/admin" nest>
58
  <AdminLayout>
59
    <Route path="/users" component={AdminUsers} />
60
    <Route path="/settings" component={AdminSettings} />
61
  </AdminLayout>
62
</Route>
63

64
// Catch-all route
65
<Route>
66
  <NotFound />
67
</Route>
68
```
69

70
### Link Component
71

72
Creates navigational links with optional active state detection and support for both standard anchor elements and custom components via asChild pattern.
73

74
```typescript { .api }
75
/**
76
 * Navigation link component with active state detection
77
 * @param props - Link configuration including destination and navigation options
78
 * @returns Anchor element or cloned child component with navigation behavior
79
 */
80
function Link<H extends BaseLocationHook = BrowserLocationHook>(
81
  props: LinkProps<H>
82
): ReturnType<FunctionComponent>;
83

84
type LinkProps<H extends BaseLocationHook = BrowserLocationHook> = NavigationalProps<H> & 
85
  AsChildProps<
86
    { children: ReactElement; onClick?: MouseEventHandler },
87
    HTMLLinkAttributes & RefAttributes<HTMLAnchorElement>
88
  >;
89

90
type NavigationalProps<H extends BaseLocationHook = BrowserLocationHook> = 
91
  ({ to: Path; href?: never } | { href: Path; to?: never }) & HookNavigationOptions<H>;
92

93
type HTMLLinkAttributes = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "className"> & {
94
  /** CSS class name - can be string or function that receives active state */
95
  className?: string | undefined | ((isActive: boolean) => string | undefined);
96
};
97

98
type AsChildProps<ComponentProps, DefaultElementProps> = 
99
  | ({ asChild?: false } & DefaultElementProps)
100
  | ({ asChild: true } & ComponentProps);
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { Link } from "wouter";
107

108
// Basic link
109
<Link href="/about">About Us</Link>
110

111
// Link with active styling
112
<Link 
113
  href="/dashboard"
114
  className={(active) => active ? "nav-link active" : "nav-link"}
115
>
116
  Dashboard
117
</Link>
118

119
// Custom component link
120
<Link href="/profile" asChild>
121
  <CustomButton>My Profile</CustomButton>
122
</Link>
123

124
// Link with navigation options
125
<Link 
126
  href="/settings" 
127
  replace={true}
128
  state={{ from: "navbar" }}
129
>
130
  Settings
131
</Link>
132
```
133

134
### Switch Component
135

136
Renders only the first matching route from its children, providing exclusive routing behavior similar to a switch statement.
137

138
```typescript { .api }
139
/**
140
 * Switch component for exclusive route matching
141
 * @param props - Switch configuration with child routes and optional location override
142
 * @returns First matching route or null if no routes match
143
 */
144
function Switch(props: SwitchProps): ReturnType<FunctionComponent>;
145

146
interface SwitchProps {
147
  /** Optional location string to match against instead of current location */
148
  location?: string;
149
  /** Child routes - typically Route components */
150
  children: ReactNode;
151
}
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { Route, Switch } from "wouter";
158

159
// Basic switch with exclusive matching
160
<Switch>
161
  <Route path="/" component={Home} />
162
  <Route path="/about" component={About} />
163
  <Route path="/contact" component={Contact} />
164
  <Route>404 Not Found</Route>
165
</Switch>
166

167
// Switch with custom location
168
<Switch location="/admin/users">
169
  <Route path="/admin/users" component={AdminUsers} />
170
  <Route path="/admin/settings" component={AdminSettings} />
171
</Switch>
172
```
173

174
### Redirect Component
175

176
Performs immediate navigation to a specified route when rendered, useful for route protection and default route handling.
177

178
```typescript { .api }
179
/**
180
 * Redirect component for immediate navigation
181
 * @param props - Redirect configuration including destination and navigation options
182
 * @returns Always returns null after triggering navigation
183
 */
184
function Redirect<H extends BaseLocationHook = BrowserLocationHook>(
185
  props: RedirectProps<H>
186
): null;
187

188
type RedirectProps<H extends BaseLocationHook = BrowserLocationHook> = NavigationalProps<H> & {
189
  children?: never;
190
};
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
import { Route, Redirect } from "wouter";
197

198
// Basic redirect
199
<Route path="/old-path">
200
  <Redirect to="/new-path" />
201
</Route>
202

203
// Conditional redirect
204
{!user && <Redirect to="/login" />}
205

206
// Redirect with state
207
<Redirect 
208
  to="/dashboard" 
209
  state={{ message: "Welcome back!" }}
210
  replace={true}
211
/>
212
```
213

214
### Router Component
215

216
Provides routing context and configuration to child components, allowing customization of location hooks, base paths, and other routing behavior.
217

218
```typescript { .api }
219
/**
220
 * Router component for providing routing context and configuration
221
 * @param props - Router configuration options and child components
222
 * @returns Context provider wrapping child components
223
 */
224
function Router(props: RouterProps): ReturnType<FunctionComponent>;
225

226
type RouterProps = RouterOptions & {
227
  children: ReactNode;
228
};
229

230
type RouterOptions = {
231
  /** Custom location hook to use instead of default browser location */
232
  hook?: BaseLocationHook;
233
  /** Custom search hook for query parameter handling */
234
  searchHook?: BaseSearchHook;
235
  /** Base path to prepend to all routes */
236
  base?: Path;
237
  /** Custom route pattern parser */
238
  parser?: Parser;
239
  /** Static path for server-side rendering */
240
  ssrPath?: Path;
241
  /** Static search string for server-side rendering */
242
  ssrSearch?: SearchString;
243
  /** Context object for tracking SSR state */
244
  ssrContext?: SsrContext;
245
  /** Custom href formatter function */
246
  hrefs?: HrefsFormatter;
247
};
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { Router, Route } from "wouter";
254
import { useHashLocation } from "wouter/use-hash-location";
255

256
// Custom router with hash routing
257
<Router hook={useHashLocation}>
258
  <Route path="/" component={Home} />
259
  <Route path="/about" component={About} />
260
</Router>
261

262
// Router with base path
263
<Router base="/app">
264
  <Route path="/dashboard" component={Dashboard} /> // matches /app/dashboard
265
  <Route path="/settings" component={Settings} />   // matches /app/settings
266
</Router>
267

268
// SSR router
269
<Router 
270
  ssrPath="/current-path"
271
  ssrSearch="?param=value"
272
  ssrContext={ssrContext}
273
>
274
  <App />
275
</Router>
276
```
277

278
## Types
279

280
```typescript { .api }
281
type Parser = (route: Path, loose?: boolean) => { pattern: RegExp; keys: string[] };
282

283
type HrefsFormatter = (href: string, router: RouterObject) => string;
284

285
type SsrContext = {
286
  redirectTo?: Path;
287
};
288

289
type StringRouteParams<T extends string> = RouteParams<T> & {
290
  [param: number]: string | undefined;
291
};
292

293
type RegexRouteParams = { 
294
  [key: string | number]: string | undefined 
295
};
296
```