0
# Reach Router
1
2
Reach Router is a React routing library that provides accessible, declarative routing solutions for React applications. It features automatic focus management, dynamic route matching, and seamless navigation with built-in accessibility support.
3
4
## Package Information
5
6
- **Package Name**: @reach/router
7
- **Package Type**: npm
8
- **Language**: JavaScript (React library)
9
- **Installation**: `npm install @reach/router`
10
11
## Core Imports
12
13
```javascript
14
import { Router, Link, navigate } from "@reach/router";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { Router, Link, navigate } = require("@reach/router");
21
```
22
23
## Basic Usage
24
25
```javascript
26
import React from "react";
27
import { Router, Link } from "@reach/router";
28
29
const Home = () => <div>Welcome Home!</div>;
30
const About = () => <div>About Us</div>;
31
const User = ({ userId }) => <div>User: {userId}</div>;
32
33
function App() {
34
return (
35
<div>
36
<nav>
37
<Link to="/">Home</Link>
38
<Link to="/about">About</Link>
39
<Link to="/users/123">User 123</Link>
40
</nav>
41
42
<Router>
43
<Home path="/" />
44
<About path="/about" />
45
<User path="/users/:userId" />
46
</Router>
47
</div>
48
);
49
}
50
```
51
52
## Architecture
53
54
Reach Router is built around several key components:
55
56
- **Router Component**: Core routing container that matches child routes against current location
57
- **Link Component**: Accessible navigation links with automatic active state management
58
- **Location Context**: React context providing location state and navigation functions
59
- **History Management**: Browser history integration with memory fallback for testing
60
- **Focus Management**: Automatic focus handling for accessibility compliance
61
- **React Hooks**: Modern hook-based API for accessing routing state
62
63
## Capabilities
64
65
### Core Routing
66
67
Essential routing components for building navigable React applications with automatic route matching and focus management.
68
69
```javascript { .api }
70
function Router(props: {
71
basepath?: string;
72
primary?: boolean;
73
children: React.ReactNode;
74
component?: string | React.ComponentType;
75
[key: string]: any;
76
}): React.ReactElement;
77
```
78
79
[Core Routing](./routing.md)
80
81
### Navigation
82
83
Link components and programmatic navigation functions for moving between routes with accessibility features and state management.
84
85
```javascript { .api }
86
const Link: React.ForwardRefExoticComponent<{
87
to: string;
88
state?: any;
89
replace?: boolean;
90
getProps?: (props: LinkProps) => object;
91
innerRef?: React.Ref<HTMLAnchorElement>;
92
} & React.AnchorHTMLAttributes<HTMLAnchorElement> & React.RefAttributes<HTMLAnchorElement>>;
93
94
function navigate(to: string | number, options?: {
95
state?: any;
96
replace?: boolean;
97
}): Promise<void>;
98
```
99
100
[Navigation](./navigation.md)
101
102
### Location and Context
103
104
Location providers and consumer components for accessing current location state and navigation functions in React components.
105
106
```javascript { .api }
107
function LocationProvider(props: {
108
history?: History;
109
children: React.ReactNode | ((context: LocationContext) => React.ReactNode);
110
}): React.ReactElement;
111
112
function Location(props: {
113
children: (context: LocationContext) => React.ReactNode;
114
}): React.ReactElement;
115
116
interface LocationContext {
117
location: Location;
118
navigate: (to: string | number, options?: NavigateOptions) => Promise<void>;
119
}
120
```
121
122
[Location and Context](./location-context.md)
123
124
### React Hooks
125
126
Modern React hooks for accessing routing state and navigation functions in functional components.
127
128
```javascript { .api }
129
function useLocation(): Location;
130
function useNavigate(): (to: string | number, options?: NavigateOptions) => Promise<void>;
131
function useParams(): Record<string, string> | null;
132
function useMatch(path: string): MatchResult | null;
133
```
134
135
[React Hooks](./hooks.md)
136
137
### History Management
138
139
History utilities for creating custom history instances and managing navigation state in different environments.
140
141
```javascript { .api }
142
function createHistory(source: LocationSource, options?: any): History;
143
function createMemorySource(initialPath?: string): LocationSource;
144
145
const globalHistory: History;
146
```
147
148
[History Management](./history.md)
149
150
### Server-Side Rendering
151
152
Components and utilities for rendering routes on the server with static location context.
153
154
```javascript { .api }
155
function ServerLocation(props: {
156
url: string;
157
children: React.ReactNode;
158
}): React.ReactElement;
159
```
160
161
[Server-Side Rendering](./server-rendering.md)
162
163
### Advanced Routing
164
165
Advanced routing patterns including redirects, conditional rendering, and route matching utilities.
166
167
```javascript { .api }
168
function Redirect(props: {
169
from?: string;
170
to: string;
171
replace?: boolean;
172
state?: any;
173
noThrow?: boolean;
174
}): React.ReactElement;
175
176
function Match(props: {
177
path: string;
178
children: (props: MatchProps) => React.ReactNode;
179
}): React.ReactElement;
180
181
function matchPath(path: string, uri: string): MatchResult | null;
182
function isRedirect(error: any): boolean;
183
function redirectTo(to: string): never;
184
```
185
186
[Advanced Routing](./advanced-routing.md)
187
188
### Utilities
189
190
Path resolution and routing utility functions for advanced routing scenarios and custom integrations.
191
192
```javascript { .api }
193
function resolve(to: string, base: string): string;
194
function insertParams(path: string, params: Record<string, any>): string;
195
function validateRedirect(from: string, to: string): boolean;
196
function shallowCompare(obj1: object, obj2: object): boolean;
197
```
198
199
[Utilities](./utilities.md)
200
201
## Types
202
203
```javascript { .api }
204
interface Location {
205
pathname: string; // URI encoded/decoded
206
search: string;
207
hash: string;
208
href?: string; // Optional in non-browser environments
209
origin?: string; // Optional in non-browser environments
210
protocol?: string; // Optional in non-browser environments
211
host?: string; // Optional in non-browser environments
212
hostname?: string; // Optional in non-browser environments
213
port?: string; // Optional in non-browser environments
214
state: any;
215
key: string; // Defaults to "initial"
216
}
217
218
interface NavigateOptions {
219
state?: any;
220
replace?: boolean;
221
}
222
223
interface MatchResult {
224
route: RouteInfo;
225
params: Record<string, string | string[]>; // Can contain arrays for splat routes
226
uri: string; // Always normalized with leading slash
227
}
228
229
interface RouteInfo {
230
path: string;
231
default?: boolean;
232
value: React.ReactElement;
233
}
234
235
interface History {
236
location: Location;
237
transitioning: boolean;
238
listen(listener: (event: { location: Location; action: string }) => void): () => void;
239
navigate(to: string | number, options?: NavigateOptions): Promise<void>;
240
}
241
242
interface LocationSource {
243
location: {
244
pathname: string;
245
search: string;
246
hash?: string;
247
href?: string;
248
origin?: string;
249
protocol?: string;
250
host?: string;
251
hostname?: string;
252
port?: string;
253
};
254
history: {
255
state: any;
256
pushState(state: any, title: string | null, url: string): void;
257
replaceState(state: any, title: string | null, url: string): void;
258
go(delta: number): void;
259
};
260
addEventListener(type: string, listener: () => void): void;
261
removeEventListener(type: string, listener: () => void): void;
262
}
263
264
interface LinkProps {
265
isCurrent: boolean;
266
isPartiallyCurrent: boolean;
267
href: string;
268
location: Location;
269
}
270
271
interface MatchProps {
272
navigate: (to: string | number, options?: NavigateOptions) => Promise<void>;
273
location: Location;
274
match: MatchResult | null;
275
}
276
```