0
# Core Routing
1

2
Essential routing components for building navigable React applications with automatic route matching and focus management.
3

4
## Capabilities
5

6
### Router Component
7

8
The main routing component that matches child routes against the current location and renders the matching component.
9

10
```javascript { .api }
11
/**
12
 * Core routing container that matches child routes against current location
13
 * @param props - Router configuration options
14
 */
15
function Router(props: {
16
  basepath?: string;
17
  primary?: boolean;
18
  children: React.ReactNode;
19
  component?: string | React.ComponentType;
20
  [key: string]: any;
21
}): React.ReactElement;
22
```
23

24
**Props:**
25
- `basepath` (string, optional) - Base path for nested routers
26
- `primary` (boolean, optional) - Whether this router manages focus (defaults to true)
27
- `children` (React.ReactNode) - Route components with path props
28
- `component` (string | React.ComponentType, optional) - Component to wrap matched route (defaults to "div")
29
- Additional props are passed to the wrapper component
30

31
**Usage Examples:**
32

33
```javascript
34
import React from "react";
35
import { Router } from "@reach/router";
36

37
// Basic routing
38
const App = () => (
39
  <Router>
40
    <Home path="/" />
41
    <About path="/about" />
42
    <Contact path="/contact" />
43
  </Router>
44
);
45

46
// Nested routing with basepath
47
const Dashboard = () => (
48
  <Router basepath="/dashboard">
49
    <Overview path="/" />
50
    <Settings path="/settings" />
51
    <Profile path="/profile" />
52
  </Router>
53
);
54

55
// Custom wrapper component
56
const App = () => (
57
  <Router component="main" className="app-router">
58
    <Home path="/" />
59
    <About path="/about" />
60
  </Router>
61
);
62
```
63

64
### Route Components
65

66
Route components are regular React components that receive special props when matched by the Router.
67

68
```javascript { .api }
69
/**
70
 * Route components receive these props when matched
71
 */
72
interface RouteComponentProps {
73
  // Path parameters extracted from the route
74
  [paramName: string]: string;
75
  // Matched URI portion
76
  uri: string;
77
  // Current location object
78
  location: Location;
79
  // Navigation function scoped to current route
80
  navigate: (to: string | number, options?: NavigateOptions) => Promise<void>;
81
  // Any additional props passed to the route component
82
  [prop: string]: any;
83
}
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
// Route with path parameters
90
const User = ({ userId, location, navigate }) => (
91
  <div>
92
    <h1>User: {userId}</h1>
93
    <p>Current path: {location.pathname}</p>
94
    <button onClick={() => navigate("/")}>Go Home</button>
95
  </div>
96
);
97

98
// Usage in Router
99
<Router>
100
  <User path="/users/:userId" />
101
</Router>
102

103
// Route with wildcard
104
const CatchAll = ({ "*": splat, location }) => (
105
  <div>
106
    <h1>Page Not Found</h1>
107
    <p>Unmatched path: {splat}</p>
108
    <p>Full location: {location.pathname}</p>
109
  </div>
110
);
111

112
<Router>
113
  <Home path="/" />
114
  <CatchAll path="/*" />
115
</Router>
116
```
117

118
### Default Routes
119

120
Routes that match when no other route matches the current path.
121

122
```javascript { .api }
123
/**
124
 * Default route component that renders when no other routes match
125
 */
126
interface DefaultRouteProps {
127
  default: true;
128
  // Standard route component props
129
  location: Location;
130
  navigate: (to: string | number, options?: NavigateOptions) => Promise<void>;
131
  uri: string;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
const NotFound = ({ location }) => (
139
  <div>
140
    <h1>404 - Page Not Found</h1>
141
    <p>Could not find {location.pathname}</p>
142
  </div>
143
);
144

145
<Router>
146
  <Home path="/" />
147
  <About path="/about" />
148
  <NotFound default />
149
</Router>
150
```
151

152
### Nested Routing
153

154
Routers can be nested to create complex routing hierarchies with relative path resolution.
155

156
**Usage Examples:**
157

158
```javascript
159
const App = () => (
160
  <Router>
161
    <Home path="/" />
162
    <Dashboard path="/dashboard/*" />
163
  </Router>
164
);
165

166
const Dashboard = ({ children }) => (
167
  <div>
168
    <nav>Dashboard Navigation</nav>
169
    <Router>
170
      <DashboardHome path="/" />
171
      <Settings path="/settings" />
172
      <Profile path="/profile" />
173
    </Router>
174
  </div>
175
);
176

177
// Alternative approach with explicit nesting
178
const Dashboard = ({ children }) => (
179
  <div>
180
    <nav>Dashboard Navigation</nav>
181
    {children}
182
  </div>
183
);
184

185
<Router>
186
  <Home path="/" />
187
  <Dashboard path="/dashboard">
188
    <DashboardHome path="/" />
189
    <Settings path="/settings" />
190
    <Profile path="/profile" />
191
  </Dashboard>
192
</Router>
193
```
194

195
### Path Patterns
196

197
Supported path pattern syntax for route matching.
198

199
```javascript { .api }
200
/**
201
 * Path pattern syntax:
202
 * - Static segments: /users/profile
203
 * - Dynamic segments: /users/:userId
204
 * - Wildcard segments: /files/*
205
 * - Named wildcards: /files/*filepath
206
 * - Optional segments: Not directly supported, use default routes
207
 */
208
```
209

210
**Path Pattern Examples:**
211

212
```javascript
213
// Static paths
214
<Home path="/" />
215
<About path="/about" />
216
<Contact path="/contact" />
217

218
// Dynamic parameters
219
<User path="/users/:userId" />
220
<Post path="/blog/:category/:postId" />
221

222
// Wildcard matching
223
<Files path="/files/*" />
224
<Admin path="/admin/*" />
225

226
// Named wildcards
227
<Files path="/files/*filepath" />
228
// Component receives filepath parameter with remaining path
229

230
// Nested routing patterns
231
<Dashboard path="/dashboard/*">
232
  <Overview path="/" />
233
  <Settings path="/settings" />
234
  <UserSettings path="/settings/:section" />
235
</Dashboard>
236
```