0
# Navigation & Routing
1

2
Programmatic navigation, route parsing, and URL generation with resource-aware navigation utilities for CRUD operations.
3

4
## Capabilities
5

6
### Core Navigation
7

8
#### useNavigation Hook
9

10
Provides high-level navigation utilities specifically designed for CRUD operations with automatic URL generation and type-safe navigation.
11

12
```typescript { .api }
13
/**
14
 * Provides navigation utilities for CRUD operations
15
 * @returns Navigation functions for different CRUD actions
16
 */
17
function useNavigation(): UseNavigationReturnType;
18

19
interface UseNavigationReturnType {
20
  /** Navigate to resource list page */
21
  list: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
22
  /** Navigate to resource create page */
23
  create: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
24
  /** Navigate to resource edit page */
25
  edit: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
26
  /** Navigate to resource show/detail page */
27
  show: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
28
  /** Navigate to resource clone page */
29
  clone: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
30
  /** Generate URL for resource list page */
31
  listUrl: (resource: string, meta?: Record<string, unknown>) => string;
32
  /** Generate URL for resource create page */
33
  createUrl: (resource: string, meta?: Record<string, unknown>) => string;
34
  /** Generate URL for resource edit page */
35
  editUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
36
  /** Generate URL for resource show/detail page */
37
  showUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
38
  /** Generate URL for resource clone page */
39
  cloneUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
40
}
41

42
type HistoryType = "push" | "replace";
43
```
44

45
**Usage Example:**
46

47
```typescript
48
import { useNavigation } from "@refinedev/core";
49

50
function PostActions({ postId }: { postId: string }) {
51
  const navigation = useNavigation();
52
  
53
  const handleEdit = () => {
54
    // Navigate to edit page
55
    navigation.edit("posts", postId);
56
  };
57
  
58
  const handleView = () => {
59
    // Navigate to show page
60
    navigation.show("posts", postId);
61
  };
62
  
63
  const handleCreateNew = () => {
64
    // Navigate to create page
65
    navigation.create("posts");
66
  };
67
  
68
  const handleClone = () => {
69
    // Navigate to clone page (create with pre-filled data)
70
    navigation.clone("posts", postId);
71
  };
72
  
73
  // Generate URLs for links
74
  const editUrl = navigation.editUrl("posts", postId);
75
  const showUrl = navigation.showUrl("posts", postId);
76
  
77
  return (
78
    <div>
79
      <button onClick={handleEdit}>Edit</button>
80
      <button onClick={handleView}>View</button>
81
      <button onClick={handleCreateNew}>Create New</button>
82
      <button onClick={handleClone}>Clone</button>
83
      
84
      <a href={editUrl}>Edit Link</a>
85
      <a href={showUrl}>View Link</a>
86
    </div>
87
  );
88
}
89
```
90

91
#### useGo Hook
92

93
Low-level programmatic navigation with full control over routing behavior and query parameters.
94

95
```typescript { .api }
96
/**
97
 * Provides programmatic navigation with full control
98
 * @returns Go function for flexible navigation
99
 */
100
function useGo(): Go;
101

102
interface Go {
103
  (options: GoConfig): void;
104
}
105

106
interface GoConfig {
107
  /** Target URL or route to navigate to */
108
  to: string;
109
  /** Navigation type - push adds to history, replace replaces current */
110
  type?: "push" | "replace";
111
  /** Query parameters to include in URL */
112
  query?: Record<string, any>;
113
  /** Navigation options */
114
  options?: {
115
    /** Whether to keep existing query parameters */
116
    keepQuery?: boolean;
117
    /** Whether to keep existing URL hash */
118
    keepHash?: boolean;
119
  };
120
}
121
```
122

123
**Usage Example:**
124

125
```typescript
126
import { useGo } from "@refinedev/core";
127

128
function NavigationComponent() {
129
  const go = useGo();
130
  
131
  const handleNavigateToPost = (postId: string) => {
132
    go({
133
      to: `/posts/${postId}`,
134
      type: "push",
135
      query: {
136
        tab: "comments",
137
        sort: "newest"
138
      },
139
      options: {
140
        keepQuery: false,
141
        keepHash: true
142
      }
143
    });
144
  };
145
  
146
  const handleReplaceRoute = () => {
147
    go({
148
      to: "/dashboard",
149
      type: "replace", // Replace current route in history
150
      query: {
151
        view: "grid"
152
      }
153
    });
154
  };
155
  
156
  return (
157
    <div>
158
      <button onClick={() => handleNavigateToPost("123")}>
159
        View Post with Comments
160
      </button>
161
      <button onClick={handleReplaceRoute}>
162
        Go to Dashboard
163
      </button>
164
    </div>
165
  );
166
}
167
```
168

169
#### useBack Hook
170

171
Navigate back in browser history with fallback options.
172

173
```typescript { .api }
174
/**
175
 * Navigate back in history with fallback
176
 * @returns Back function for history navigation
177
 */
178
function useBack(): Back;
179

180
interface Back {
181
  (): void;
182
}
183
```
184

185
**Usage Example:**
186

187
```typescript
188
import { useBack } from "@refinedev/core";
189

190
function BackButton() {
191
  const back = useBack();
192
  
193
  return (
194
    <button onClick={back}>
195
      ← Go Back
196
    </button>
197
  );
198
}
199
```
200

201
### Route Information
202

203
#### useParsed Hook
204

205
Retrieves and parses current route information with resource and parameter extraction.
206

207
```typescript { .api }
208
/**
209
 * Gets parsed route information
210
 * @returns Parsed route parameters and resource information
211
 */
212
function useParsed(): ParsedParams;
213

214
interface ParsedParams {
215
  /** Current pathname */
216
  pathname: string;
217
  /** Extracted route parameters */
218
  params: Record<string, string | string[]>;
219
  /** Identified resource from route */
220
  resource?: IResourceItem;
221
  /** Current action (list, create, edit, show, clone) */
222
  action?: Action;
223
  /** Record ID if present in route */
224
  id?: BaseKey;
225
}
226

227
interface IResourceItem {
228
  /** Resource name */
229
  name: string;
230
  /** Display label */
231
  label?: string;
232
  /** Resource icon */
233
  icon?: React.ReactNode;
234
  /** Route definitions */
235
  route?: string;
236
  /** Whether resource can be deleted */
237
  canDelete?: boolean;
238
  /** Parent resource name */
239
  parentName?: string;
240
  /** Resource metadata */
241
  meta?: Record<string, any>;
242
}
243

244
type Action = "list" | "create" | "edit" | "show" | "clone";
245
```
246

247
**Usage Example:**
248

249
```typescript
250
import { useParsed } from "@refinedev/core";
251

252
function RouteInfo() {
253
  const { pathname, params, resource, action, id } = useParsed();
254
  
255
  return (
256
    <div>
257
      <p>Current Path: {pathname}</p>
258
      <p>Resource: {resource?.name}</p>
259
      <p>Action: {action}</p>
260
      <p>ID: {id}</p>
261
      <p>Params: {JSON.stringify(params)}</p>
262
    </div>
263
  );
264
}
265

266
// Usage in a breadcrumb component
267
function Breadcrumb() {
268
  const { resource, action, id } = useParsed();
269
  
270
  const breadcrumbItems = [
271
    { label: "Home", url: "/" },
272
    { label: resource?.label || resource?.name, url: `/${resource?.name}` }
273
  ];
274
  
275
  if (action === "edit" && id) {
276
    breadcrumbItems.push({
277
      label: `Edit ${id}`,
278
      url: `/${resource?.name}/edit/${id}`
279
    });
280
  } else if (action === "create") {
281
    breadcrumbItems.push({
282
      label: "Create",
283
      url: `/${resource?.name}/create`
284
    });
285
  }
286
  
287
  return (
288
    <nav>
289
      {breadcrumbItems.map((item, index) => (
290
        <span key={index}>
291
          <a href={item.url}>{item.label}</a>
292
          {index < breadcrumbItems.length - 1 && " > "}
293
        </span>
294
      ))}
295
    </nav>
296
  );
297
}
298
```
299

300
### URL Management
301

302
#### useLink Hook
303

304
Creates router-aware links with proper navigation handling.
305

306
```typescript { .api }
307
/**
308
 * Creates router-aware links
309
 * @param params - Link configuration
310
 * @returns Link component with router integration
311
 */
312
function useLink(): LinkComponent;
313

314
interface LinkComponent {
315
  (props: LinkProps): JSX.Element;
316
}
317

318
interface LinkProps {
319
  /** Destination URL */
320
  to: string;
321
  /** Link content */
322
  children: React.ReactNode;
323
  /** Whether to replace current history entry */
324
  replace?: boolean;
325
  /** Additional HTML attributes */
326
  [key: string]: any;
327
}
328
```
329

330
#### Router Provider Integration
331

332
Integration with various router providers for seamless navigation.
333

334
```typescript { .api }
335
/**
336
 * Router provider interface for navigation integration
337
 */
338
interface RouterProvider {
339
  /** Navigate to a route */
340
  go: () => Go;
341
  /** Navigate back in history */
342
  back: () => Back;
343
  /** Parse current route */
344
  parse: () => ParsedParams;
345
  /** Create a Link component */
346
  Link: LinkComponent;
347
}
348
```
349

350
### Menu & Breadcrumb Utilities
351

352
#### useMenu Hook
353

354
Generates navigation menu items from resources with proper nesting and permissions.
355

356
```typescript { .api }
357
/**
358
 * Generates menu items from resources
359
 * @param params - Menu configuration
360
 * @returns Menu items and selection state
361
 */
362
function useMenu(params?: UseMenuConfig): UseMenuReturnType;
363

364
interface UseMenuConfig {
365
  /** Hide items that require missing parameters */
366
  hideOnMissingParameter?: boolean;
367
  /** Additional metadata for menu generation */
368
  meta?: Record<string, unknown>;
369
}
370

371
interface UseMenuReturnType {
372
  /** Generated menu items */
373
  menuItems: MenuItem[];
374
  /** Currently selected menu item key */
375
  selectedKey: string | undefined;
376
}
377

378
interface MenuItem {
379
  /** Menu item key */
380
  key: string;
381
  /** Display name */
382
  name: string;
383
  /** Display label */
384
  label?: string;
385
  /** Menu icon */
386
  icon?: React.ReactNode;
387
  /** Navigation URL */
388
  url?: string;
389
  /** Navigation route */
390
  route?: string;
391
  /** Parent menu item */
392
  parentName?: string;
393
  /** Child menu items */
394
  children?: MenuItem[];
395
  /** Additional metadata */
396
  meta?: Record<string, any>;
397
}
398
```
399

400
**Usage Example:**
401

402
```typescript
403
import { useMenu } from "@refinedev/core";
404

405
function NavigationMenu() {
406
  const { menuItems, selectedKey } = useMenu();
407
  
408
  const renderMenuItem = (item: MenuItem) => (
409
    <li key={item.key} className={selectedKey === item.key ? "active" : ""}>
410
      <a href={item.route}>
411
        {item.icon}
412
        <span>{item.label || item.name}</span>
413
      </a>
414
      {item.children && (
415
        <ul>
416
          {item.children.map(renderMenuItem)}
417
        </ul>
418
      )}
419
    </li>
420
  );
421
  
422
  return (
423
    <nav>
424
      <ul>
425
        {menuItems.map(renderMenuItem)}
426
      </ul>
427
    </nav>
428
  );
429
}
430
```
431

432
#### useBreadcrumb Hook
433

434
Generates breadcrumb navigation from current route and resource hierarchy.
435

436
```typescript { .api }
437
/**
438
 * Generates breadcrumb navigation
439
 * @returns Breadcrumb items for current route
440
 */
441
function useBreadcrumb(): UseBreadcrumbReturnType;
442

443
interface UseBreadcrumbReturnType {
444
  /** Breadcrumb items */
445
  breadcrumbs: BreadcrumbItem[];
446
}
447

448
interface BreadcrumbItem {
449
  /** Breadcrumb label */
450
  label: string;
451
  /** Navigation URL */
452
  href?: string;
453
  /** Menu icon */
454
  icon?: React.ReactNode;
455
}
456
```
457

458
**Usage Example:**
459

460
```typescript
461
import { useBreadcrumb } from "@refinedev/core";
462

463
function BreadcrumbNavigation() {
464
  const { breadcrumbs } = useBreadcrumb();
465
  
466
  return (
467
    <nav aria-label="Breadcrumb">
468
      <ol>
469
        {breadcrumbs.map((crumb, index) => (
470
          <li key={index}>
471
            {crumb.href ? (
472
              <a href={crumb.href}>
473
                {crumb.icon}
474
                {crumb.label}
475
              </a>
476
            ) : (
477
              <span>
478
                {crumb.icon}
479
                {crumb.label}
480
              </span>
481
            )}
482
            {index < breadcrumbs.length - 1 && <span> / </span>}
483
          </li>
484
        ))}
485
      </ol>
486
    </nav>
487
  );
488
}
489
```
490

491
### Advanced Navigation Patterns
492

493
#### Nested Resources Navigation
494

495
Handle navigation for nested resources with parent-child relationships.
496

497
```typescript { .api }
498
/**
499
 * Navigation utilities for nested resources
500
 */
501
interface NestedResourceNavigation {
502
  /** Navigate to nested resource list */
503
  listNested: (parentResource: string, parentId: BaseKey, childResource: string) => void;
504
  /** Navigate to nested resource create */
505
  createNested: (parentResource: string, parentId: BaseKey, childResource: string) => void;
506
  /** Generate nested resource URLs */
507
  nestedUrl: (parentResource: string, parentId: BaseKey, childResource: string, action?: Action, childId?: BaseKey) => string;
508
}
509
```
510

511
**Usage Example:**
512

513
```typescript
514
// Navigate to comments for a specific post
515
const handleViewComments = (postId: string) => {
516
  navigation.listNested("posts", postId, "comments");
517
  // Results in: /posts/123/comments
518
};
519

520
// Create new comment for a post
521
const handleCreateComment = (postId: string) => {
522
  navigation.createNested("posts", postId, "comments");
523
  // Results in: /posts/123/comments/create
524
};
525
```
526

527
## Types
528

529
```typescript { .api }
530
interface RouteParams {
531
  /** Resource name from route */
532
  resource?: string;
533
  /** Action from route */
534
  action?: string;
535
  /** Record ID from route */
536
  id?: BaseKey;
537
  /** Additional route parameters */
538
  [key: string]: string | number | undefined;
539
}
540

541
interface NavigationContext {
542
  /** Current route information */
543
  current: ParsedParams;
544
  /** Navigation history */
545
  history: string[];
546
  /** Whether navigation is in progress */
547
  isNavigating: boolean;
548
}
549

550
interface RedirectConfig {
551
  /** Target route for redirect */
552
  to: string;
553
  /** Redirect type */
554
  type?: "push" | "replace";
555
  /** Query parameters for redirect */
556
  query?: Record<string, any>;
557
}
558
```