0
# Navigation & Routing
1

2
Navigation utilities and routing integration for managing URL changes and programmatic navigation between microfrontends.
3

4
## Capabilities
5

6
### Navigate to URL
7

8
Programmatically navigate to a URL within the single-spa application. This function integrates with the browser's history API and triggers appropriate application mounting/unmounting.
9

10
```javascript { .api }
11
/**
12
 * Navigate to a URL programmatically
13
 * @param obj - URL string or event object with currentTarget.href
14
 * @param opts - Optional navigation options
15
 */
16
function navigateToUrl(
17
  obj: string | { currentTarget: { href: string }, preventDefault: any },
18
  opts?: Object
19
): void;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
import { navigateToUrl } from "single-spa";
26

27
// Navigate with URL string
28
navigateToUrl("/products/123");
29

30
// Navigate from click event
31
function handleNavigation(event) {
32
  navigateToUrl(event); // Automatically extracts URL from event.currentTarget.href
33
}
34

35
// Navigate from anchor element
36
const link = document.querySelector('a[href="/dashboard"]');
37
navigateToUrl(link);
38

39
// Navigate with options
40
navigateToUrl("/analytics", { 
41
  state: { from: "dashboard" },
42
  replace: true 
43
});
44
```
45

46
### Trigger Application Changes
47

48
Manually triggers the process of mounting and unmounting applications based on the current URL. Useful for forcing a re-evaluation of which applications should be active.
49

50
```javascript { .api }
51
/**
52
 * Manually trigger application mount/unmount based on current route
53
 * @returns Promise that resolves when all application changes are complete
54
 */
55
function triggerAppChange(): Promise<any>;
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
import { triggerAppChange } from "single-spa";
62

63
// Force re-evaluation of active applications
64
await triggerAppChange();
65

66
// Trigger after dynamic route changes
67
function updateUserPermissions() {
68
  // Update user permissions logic
69
  // Force single-spa to re-evaluate which apps should be active
70
  triggerAppChange();
71
}
72

73
// Use in error recovery
74
async function recoverFromError() {
75
  try {
76
    await triggerAppChange();
77
    console.log("Applications successfully re-evaluated");
78
  } catch (error) {
79
    console.error("Failed to trigger application changes:", error);
80
  }
81
}
82
```
83

84
### Patch History API
85

86
Patches the browser's history API to integrate with single-spa routing. This is automatically called by `start()` but can be called manually if needed.
87

88
```javascript { .api }
89
/**
90
 * Patch browser history API for single-spa integration
91
 * @param opts - Optional configuration options
92
 */
93
function patchHistoryApi(opts?: StartOpts): void;
94

95
interface StartOpts {
96
  urlRerouteOnly?: boolean;
97
}
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
import { patchHistoryApi } from "single-spa";
104

105
// Patch history API manually (usually not needed)
106
patchHistoryApi();
107

108
// Patch with URL-only rerouting
109
patchHistoryApi({ urlRerouteOnly: true });
110
```
111

112
## Custom Event Integration
113

114
Single-spa emits custom events during navigation and application lifecycle changes:
115

116
```javascript
117
// Listen for single-spa routing events
118
window.addEventListener("single-spa:routing-event", (event) => {
119
  console.log("Navigation occurred:", event.detail);
120
});
121

122
// Listen for application lifecycle events
123
window.addEventListener("single-spa:app-change", (event) => {
124
  console.log("Applications changed:", event.detail);
125
});
126
```
127

128
## Routing Integration Patterns
129

130
### Hash-based Routing
131

132
```javascript
133
import { registerApplication, navigateToUrl } from "single-spa";
134

135
// Register applications for hash-based routing
136
registerApplication({
137
  name: "products",
138
  app: () => import("./products/products.app.js"),
139
  activeWhen: (location) => location.hash.startsWith("#/products")
140
});
141

142
// Navigate using hash
143
navigateToUrl("#/products/electronics");
144
```
145

146
### Query Parameter Routing
147

148
```javascript
149
import { registerApplication, navigateToUrl } from "single-spa";
150

151
// Route based on query parameters
152
registerApplication({
153
  name: "modal",
154
  app: () => import("./modal/modal.app.js"),
155
  activeWhen: (location) => {
156
    const params = new URLSearchParams(location.search);
157
    return params.has("modal");
158
  }
159
});
160

161
// Navigate with query parameters
162
navigateToUrl("/dashboard?modal=user-settings");
163
```
164

165
### Nested Route Management
166

167
```javascript
168
import { registerApplication, navigateToUrl } from "single-spa";
169

170
// Parent application
171
registerApplication({
172
  name: "admin",
173
  app: () => import("./admin/admin.app.js"),
174
  activeWhen: "/admin"
175
});
176

177
// Child applications within admin
178
registerApplication({
179
  name: "admin-users",
180
  app: () => import("./admin/users/users.app.js"),
181
  activeWhen: "/admin/users"
182
});
183

184
registerApplication({
185
  name: "admin-settings",
186
  app: () => import("./admin/settings/settings.app.js"),
187
  activeWhen: "/admin/settings"
188
});
189

190
// Navigate between nested routes
191
navigateToUrl("/admin/users/profile/123");
192
```
193

194
## Error Handling
195

196
```javascript
197
import { navigateToUrl, addErrorHandler } from "single-spa";
198

199
// Handle navigation errors
200
addErrorHandler((error) => {
201
  if (error.message.includes("navigation")) {
202
    console.error("Navigation error:", error);
203
    // Fallback navigation
204
    navigateToUrl("/error");
205
  }
206
});
207

208
// Safe navigation with error handling
209
function safeNavigate(url) {
210
  try {
211
    navigateToUrl(url);
212
  } catch (error) {
213
    console.error("Navigation failed:", error);
214
    // Handle navigation failure
215
  }
216
}
217
```