0
# Router Components
1

2
Core router components for setting up routing in React applications, providing the foundation for client-side navigation and route rendering.
3

4
## Capabilities
5

6
### BrowserRouter
7

8
Uses HTML5 history API for clean URLs without hash symbols.
9

10
```typescript { .api }
11
/**
12
 * Router that uses HTML5 history API for navigation
13
 * @param props - BrowserRouter configuration options
14
 * @returns Router component for browser-based routing
15
 */
16
function BrowserRouter(props: BrowserRouterProps): JSX.Element;
17

18
interface BrowserRouterProps {
19
  /** Base URL for all locations. Useful for sub-directory deployments */
20
  basename?: string;
21
  /** React children to render inside the router */
22
  children?: React.ReactNode;
23
  /** Window object to use for history (useful for testing) */
24
  window?: Window;
25
}
26
```
27

28
**Usage Example:**
29

30
```tsx
31
import { BrowserRouter, Routes, Route } from "react-router-dom";
32

33
function App() {
34
  return (
35
    <BrowserRouter basename="/my-app">
36
      <Routes>
37
        <Route path="/" element={<Home />} />
38
        <Route path="/about" element={<About />} />
39
      </Routes>
40
    </BrowserRouter>
41
  );
42
}
43
```
44

45
### HashRouter
46

47
Uses hash portion of URL for routing, compatible with older browsers and static file servers.
48

49
```typescript { .api }
50
/**
51
 * Router that uses hash-based routing for compatibility
52
 * @param props - HashRouter configuration options
53
 * @returns Router component using hash-based navigation
54
 */
55
function HashRouter(props: HashRouterProps): JSX.Element;
56

57
interface HashRouterProps {
58
  /** Base URL for all locations */
59
  basename?: string;
60
  /** React children to render inside the router */
61
  children?: React.ReactNode;
62
  /** Window object to use for history */
63
  window?: Window;
64
}
65
```
66

67
### MemoryRouter
68

69
Keeps history in memory, perfect for testing and non-browser environments.
70

71
```typescript { .api }
72
/**
73
 * Router that stores location in memory, ideal for testing
74
 * @param props - MemoryRouter configuration options
75
 * @returns Router component with in-memory navigation
76
 */
77
function MemoryRouter(props: MemoryRouterProps): JSX.Element;
78

79
interface MemoryRouterProps {
80
  /** Base URL for all locations */
81
  basename?: string;
82
  /** React children to render inside the router */
83
  children?: React.ReactNode;
84
  /** Initial entries in the history stack */
85
  initialEntries?: InitialEntry[];
86
  /** Initial index in the history stack */
87
  initialIndex?: number;
88
}
89

90
type InitialEntry = string | Partial<Location>;
91
```
92

93
### Router
94

95
Low-level router component that accepts a history instance directly.
96

97
```typescript { .api }
98
/**
99
 * Low-level router component accepting custom history
100
 * @param props - Router configuration with history instance
101
 * @returns Base router component
102
 */
103
function Router(props: RouterProps): JSX.Element;
104

105
interface RouterProps {
106
  /** Base URL for all locations */
107
  basename?: string;
108
  /** React children to render inside the router */
109
  children?: React.ReactNode;
110
  /** History instance to use for navigation */
111
  location: Partial<Location> | string;
112
  /** Navigation function */
113
  navigationType?: NavigationType;
114
  /** Navigator instance */
115
  navigator: Navigator;
116
  /** Static mode flag */
117
  static?: boolean;
118
}
119

120
interface Navigator {
121
  createHref: (to: To) => string;
122
  push: (to: To, state?: any) => void;
123
  replace: (to: To, state?: any) => void;
124
  go: (delta: number) => void;
125
  back: () => void;
126
  forward: () => void;
127
}
128
```
129

130
### RouterProvider
131

132
High-level router component that works with router instances created by `createBrowserRouter` and similar functions.
133

134
```typescript { .api }
135
/**
136
 * High-level router provider for data-enabled routers
137
 * @param props - RouterProvider configuration with router instance
138
 * @returns Router provider component with full feature support
139
 */
140
function RouterProvider(props: RouterProviderProps): JSX.Element;
141

142
interface RouterProviderProps {
143
  /** Data router instance created by createBrowserRouter or similar */
144
  router: DataRouter;
145
  /** Error handler for uncaught errors during rendering/loading */
146
  unstable_onError?: (error: any, errorInfo: React.ErrorInfo) => void;
147
}
148

149
interface DataRouter {
150
  /** Initialize the router and start listening to history */
151
  initialize(): void;
152
  /** Subscribe to router state changes */
153
  subscribe(fn: RouterSubscriber): () => void;
154
  /** Navigate to a new location */
155
  navigate(to: To, opts?: RouterNavigateOptions): Promise<void>;
156
  /** Current router state */
157
  state: RouterState;
158
  /** Dispose of the router and clean up listeners */
159
  dispose(): void;
160
}
161
```
162

163
**Usage Example:**
164

165
```tsx
166
import { createBrowserRouter, RouterProvider } from "react-router-dom";
167

168
const router = createBrowserRouter([
169
  {
170
    path: "/",
171
    element: <Root />,
172
    loader: rootLoader,
173
    children: [
174
      {
175
        path: "dashboard",
176
        element: <Dashboard />,
177
        loader: dashboardLoader,
178
      },
179
    ],
180
  },
181
]);
182

183
function App() {
184
  return <RouterProvider router={router} />;
185
}
186
```
187

188
### HydratedRouter
189

190
Specialized router for React Server Components and framework-mode applications.
191

192
```typescript { .api }
193
/**
194
 * Framework-mode router for hydrating from server state
195
 * @param props - HydratedRouter configuration options
196
 * @returns Hydrated router component for SSR applications
197
 */
198
function HydratedRouter(props: HydratedRouterProps): JSX.Element;
199

200
interface HydratedRouterProps {
201
  /** Context function for clientAction/clientLoader */
202
  unstable_getContext?: RouterInit["unstable_getContext"];
203
  /** Error handler for application errors */
204
  unstable_onError?: (error: any, errorInfo: React.ErrorInfo) => void;
205
}
206

207
interface RouterInit {
208
  unstable_getContext?: () => any;
209
}
210
```
211

212
## Router Selection Guide
213

214
- **BrowserRouter**: Default choice for modern web applications with clean URLs
215
- **HashRouter**: Use when deploying to static file servers or need IE9 support  
216
- **MemoryRouter**: Perfect for testing, React Native, or non-DOM environments
217
- **RouterProvider**: Use with `createBrowserRouter` for data loading features
218
- **HydratedRouter**: Use in React Server Components or framework-mode applications
219
- **Router**: Advanced use cases with custom history management