0
# Navigation Components
1

2
Navigation and linking components for building consistent user flows, site structure, and wayfinding experiences. These components provide accessible navigation patterns with proper ARIA support and keyboard interaction.
3

4
## Capabilities
5

6
### Navigation
7

8
Main navigation component for sidebar navigation with hierarchical structure, user information, and contextual actions.
9

10
```typescript { .api }
11
/**
12
 * Main navigation component for sidebar navigation
13
 * @param location - Current location/URL for active state
14
 * @param children - Navigation items and sections
15
 * @param contextControl - Context-specific controls
16
 * @returns JSX element with navigation sidebar
17
 */
18
function Navigation(props: NavigationProps): JSX.Element;
19

20
interface NavigationProps {
21
  /** Current location for determining active items */
22
  location: string;
23
  /** Navigation items and content */
24
  children?: React.ReactNode;
25
  /** Context control component */
26
  contextControl?: React.ReactNode;
27
  /** Navigation dismissal handler (mobile) */
28
  onDismiss?: () => void;
29
  /** ARIA label for navigation */
30
  ariaLabelledBy?: string;
31
}
32

33
/**
34
 * Navigation section for grouping related items
35
 * @param title - Section title
36
 * @param items - Navigation items in section
37
 * @param action - Section-level action
38
 * @returns JSX element with navigation section
39
 */
40
function NavigationSection(props: NavigationSectionProps): JSX.Element;
41

42
interface NavigationSectionProps {
43
  /** Section title */
44
  title?: string;
45
  /** Navigation items */
46
  items: NavigationItemProps[];
47
  /** Section action */
48
  action?: NavigationSectionAction;
49
  /** Section separator */
50
  separator?: boolean;
51
  /** Fill available space */
52
  fill?: boolean;
53
  /** Rollup configuration */
54
  rollup?: NavigationRollup;
55
}
56

57
/**
58
 * Individual navigation item
59
 * @param label - Item label text
60
 * @param url - Navigation URL
61
 * @param icon - Item icon
62
 * @param badge - Item badge content
63
 * @returns JSX element with navigation item
64
 */
65
function NavigationItem(props: NavigationItemProps): JSX.Element;
66

67
interface NavigationItemProps {
68
  /** Item label */
69
  label: string;
70
  /** Navigation URL */
71
  url?: string;
72
  /** Item icon */
73
  icon?: IconSource;
74
  /** Badge content */
75
  badge?: string | React.ReactNode;
76
  /** Sub-navigation items */
77
  subNavigationItems?: SubNavigationItem[];
78
  /** Secondary action */
79
  secondaryAction?: SecondaryAction;
80
  /** Disabled state */
81
  disabled?: boolean;
82
  /** New indicator */
83
  new?: boolean;
84
  /** Click handler */
85
  onClick?: () => void;
86
  /** Match paths exactly */
87
  exactMatch?: boolean;
88
  /** External link */
89
  external?: boolean;
90
  /** Selected state */
91
  selected?: boolean;
92
  /** Display name for screen readers */
93
  displayName?: string;
94
  /** Additional accessibility label */
95
  accessibilityLabel?: string;
96
}
97

98
interface SubNavigationItem {
99
  /** Sub-item label */
100
  label: string;
101
  /** Sub-item URL */
102
  url: string;
103
  /** Disabled state */
104
  disabled?: boolean;
105
  /** New indicator */
106
  new?: boolean;
107
  /** Click handler */
108
  onClick?: () => void;
109
}
110

111
interface NavigationSectionAction {
112
  /** Action icon */
113
  icon: IconSource;
114
  /** Accessibility label */
115
  accessibilityLabel: string;
116
  /** Action handler */
117
  onClick: () => void;
118
}
119

120
interface NavigationRollup {
121
  /** Rollup after count */
122
  after: number;
123
  /** View action label */
124
  view: string;
125
  /** Hide action label */
126
  hide: string;
127
  /** Rollup action handler */
128
  activePath: string;
129
}
130

131
interface SecondaryAction {
132
  /** Action URL */
133
  url?: string;
134
  /** Action accessibility label */
135
  accessibilityLabel: string;
136
  /** Action icon */
137
  icon: IconSource;
138
  /** Action tooltip */
139
  tooltip?: string;
140
  /** Action handler */
141
  onClick?: () => void;
142
}
143
```
144

145
**Usage Example:**
146

147
```typescript
148
import React from 'react';
149
import { Navigation, Icon } from '@shopify/polaris';
150
import { HomeIcon, ProductIcon, OrderIcon } from '@shopify/polaris-icons';
151

152
function AppNavigation() {
153
  const navigationItems = [
154
    {
155
      label: 'Home',
156
      icon: HomeIcon,
157
      url: '/home',
158
    },
159
    {
160
      label: 'Products',
161
      icon: ProductIcon,
162
      url: '/products',
163
      badge: 'New',
164
      subNavigationItems: [
165
        { label: 'All products', url: '/products' },
166
        { label: 'Inventory', url: '/products/inventory' },
167
        { label: 'Collections', url: '/products/collections' },
168
      ],
169
    },
170
    {
171
      label: 'Orders',
172
      icon: OrderIcon,
173
      url: '/orders',
174
      badge: '15',
175
    },
176
  ];
177

178
  return (
179
    <Navigation location="/products">
180
      <Navigation.Section
181
        items={navigationItems}
182
      />
183
    </Navigation>
184
  );
185
}
186
```
187

188
### Navigation Utilities
189

190
Utility function for determining active navigation items based on current location.
191

192
```typescript { .api }
193
/**
194
 * Determine if a navigation item should be marked as active
195
 * @param item - Navigation item to check
196
 * @param currentPath - Current path/location
197
 * @returns Whether item should be active
198
 */
199
function isNavigationItemActive(
200
  item: NavigationItemProps,
201
  currentPath: string
202
): boolean;
203
```
204

205
### Link
206

207
Basic link component with support for external links, accessibility features, and consistent styling.
208

209
```typescript { .api }
210
/**
211
 * Basic link component with accessibility and styling
212
 * @param children - Link content
213
 * @param url - Link destination URL
214
 * @param external - External link indicator
215
 * @returns JSX element with link
216
 */
217
function Link(props: LinkProps): JSX.Element;
218

219
interface LinkProps {
220
  /** Link content */
221
  children?: React.ReactNode;
222
  /** Link URL */
223
  url?: string;
224
  /** External link */
225
  external?: boolean;
226
  /** Link ID */
227
  id?: string;
228
  /** Link role */
229
  role?: string;
230
  /** ARIA describedby */
231
  ariaDescribedBy?: string;
232
  /** Click handler */
233
  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
234
  /** Remove underline */
235
  removeUnderline?: boolean;
236
  /** Monospace font */
237
  monochrome?: boolean;
238
  /** Data attributes */
239
  dataPolarisUnstyled?: boolean;
240
}
241
```
242

243
### UnstyledLink
244

245
Unstyled link component providing basic link functionality without Polaris styling.
246

247
```typescript { .api }
248
/**
249
 * Unstyled link component without Polaris styling
250
 * @param children - Link content
251
 * @param url - Link destination
252
 * @param external - External link indicator
253
 * @returns JSX element with basic link
254
 */
255
function UnstyledLink(props: UnstyledLinkProps): JSX.Element;
256

257
interface UnstyledLinkProps {
258
  /** Link content */
259
  children?: React.ReactNode;
260
  /** Link URL */
261
  url?: string;
262
  /** External link */
263
  external?: boolean;
264
  /** Link ID */
265
  id?: string;
266
  /** Click handler */
267
  onClick?: () => void;
268
  /** Additional class names */
269
  className?: string;
270
  /** ARIA label */
271
  ariaLabel?: string;
272
}
273
```
274

275
### Breadcrumbs
276

277
Breadcrumb navigation component showing the current page's location within the site hierarchy.
278

279
```typescript { .api }
280
/**
281
 * Breadcrumb navigation showing page hierarchy
282
 * @param breadcrumbs - Array of breadcrumb items
283
 * @returns JSX element with breadcrumb navigation
284
 */
285
function Breadcrumbs(props: BreadcrumbsProps): JSX.Element;
286

287
interface BreadcrumbsProps {
288
  /** Array of breadcrumb items */
289
  breadcrumbs: Breadcrumb[];
290
}
291

292
interface Breadcrumb {
293
  /** Breadcrumb content/label */
294
  content: string;
295
  /** Breadcrumb URL */
296
  url?: string;
297
  /** Click handler */
298
  onAction?: () => void;
299
  /** Target for link */
300
  target?: Target;
301
  /** Accessibility label */
302
  accessibilityLabel?: string;
303
}
304

305
/** Link target values */
306
type Target = '_blank' | '_self' | '_parent' | '_top';
307
```
308

309
**Usage Example:**
310

311
```typescript
312
import React from 'react';
313
import { Breadcrumbs, Page, Card } from '@shopify/polaris';
314

315
function ProductDetailPage() {
316
  const breadcrumbs = [
317
    { content: 'Products', url: '/products' },
318
    { content: 'Clothing', url: '/products/clothing' },
319
  ];
320

321
  return (
322
    <Page
323
      title="Vintage T-Shirt"
324
      breadcrumbs={breadcrumbs}
325
    >
326
      <Card>
327
        {/* Product details */}
328
      </Card>
329
    </Page>
330
  );
331
}
332
```
333

334
### Pagination
335

336
Page navigation component with previous/next controls and page information display.
337

338
```typescript { .api }
339
/**
340
 * Page navigation with previous/next controls
341
 * @param hasPrevious - Has previous page
342
 * @param onPrevious - Previous page handler
343
 * @param hasNext - Has next page
344
 * @param onNext - Next page handler
345
 * @param label - Pagination accessibility label
346
 * @returns JSX element with pagination controls
347
 */
348
function Pagination(props: PaginationProps): JSX.Element;
349

350
interface PaginationProps {
351
  /** Has previous page */
352
  hasPrevious?: boolean;
353
  /** Previous page click handler */
354
  onPrevious?: () => void;
355
  /** Has next page */
356
  hasNext?: boolean;
357
  /** Next page click handler */
358
  onNext?: () => void;
359
  /** Accessibility label */
360
  label: string;
361
  /** Next button tooltip */
362
  nextTooltip?: string;
363
  /** Previous button tooltip */
364
  previousTooltip?: string;
365
  /** Next button accessibility label */
366
  nextLabel?: string;
367
  /** Previous button accessibility label */
368
  previousLabel?: string;
369
  /** Previous button keys for keyboard navigation */
370
  previousKeys?: Key[];
371
  /** Next button keys for keyboard navigation */
372
  nextKeys?: Key[];
373
  /** Page information display */
374
  type?: 'page' | 'table';
375
}
376
```
377

378
**Usage Example:**
379

380
```typescript
381
import React, { useState } from 'react';
382
import { Pagination, Card, DataTable } from '@shopify/polaris';
383

384
function PaginatedTable() {
385
  const [currentPage, setCurrentPage] = useState(1);
386
  const totalPages = 10;
387

388
  const handlePrevious = () => {
389
    if (currentPage > 1) {
390
      setCurrentPage(currentPage - 1);
391
    }
392
  };
393

394
  const handleNext = () => {
395
    if (currentPage < totalPages) {
396
      setCurrentPage(currentPage + 1);
397
    }
398
  };
399

400
  return (
401
    <Card>
402
      <DataTable
403
        // ... table props
404
      />
405
      <Pagination
406
        hasPrevious={currentPage > 1}
407
        onPrevious={handlePrevious}
408
        hasNext={currentPage < totalPages}
409
        onNext={handleNext}
410
        label={`Page ${currentPage} of ${totalPages}`}
411
      />
412
    </Card>
413
  );
414
}
415
```
416

417
## Navigation Types
418

419
```typescript { .api }
420
/** Keyboard key enum for navigation shortcuts */
421
enum Key {
422
  Backspace = 'Backspace',
423
  Tab = 'Tab',
424
  Enter = 'Enter',
425
  Shift = 'Shift',
426
  Control = 'Control',
427
  Alt = 'Alt',
428
  Escape = 'Escape',
429
  Space = ' ',
430
  PageUp = 'PageUp',
431
  PageDown = 'PageDown',
432
  End = 'End',
433
  Home = 'Home',
434
  LeftArrow = 'ArrowLeft',
435
  UpArrow = 'ArrowUp',
436
  RightArrow = 'ArrowRight',
437
  DownArrow = 'ArrowDown',
438
  Delete = 'Delete',
439
}
440

441
/** Icon source type for navigation items */
442
type IconSource = React.ComponentType<any> | 'placeholder' | string;
443

444
/** Action interface for navigation actions */
445
interface Action {
446
  /** Action content */
447
  content?: string;
448
  /** Accessibility label */
449
  accessibilityLabel?: string;
450
  /** Action URL */
451
  url?: string;
452
  /** External link */
453
  external?: boolean;
454
  /** Action callback */
455
  onAction?(): void;
456
  /** Mouse enter handler */
457
  onMouseEnter?(): void;
458
  /** Touch start handler */
459
  onTouchStart?(): void;
460
}
461
```
462

463
### FooterHelp
464

465
Footer help component for providing contextual assistance and links to additional resources at the bottom of pages.
466

467
```typescript { .api }
468
/**
469
 * Footer help component for contextual assistance
470
 * @param children - Help content and links
471
 * @returns JSX element with footer help information
472
 */
473
function FooterHelp(props: FooterHelpProps): JSX.Element;
474

475
interface FooterHelpProps {
476
  /** The content to display inside the footer help */
477
  children?: React.ReactNode;
478
}
479
```
480

481
### TopBar
482

483
Top navigation bar component that provides global navigation, search, user menu, and notification access across the application.
484

485
```typescript { .api }
486
/**
487
 * Global top navigation bar
488
 * @param showNavigationToggle - Whether to show navigation toggle
489
 * @param userMenu - User account menu
490
 * @param searchField - Global search field
491
 * @returns JSX element with top navigation bar
492
 */
493
function TopBar(props: TopBarProps): JSX.Element;
494

495
interface TopBarProps {
496
  /** Whether to show the navigation toggle button */
497
  showNavigationToggle?: boolean;
498
  /** User menu for the top bar */
499
  userMenu?: React.ReactNode;
500
  /** A search field for the top bar */
501
  searchField?: React.ReactNode;
502
  /** A global search field for the top bar */
503
  searchResults?: React.ReactNode;
504
  /** A slot for search result popup */
505
  searchResultsVisible?: boolean;
506
  /** Callback when the search results are dismissed */
507
  onSearchResultsDismiss?(): void;
508
  /** Whether the search results overlay is visible */
509
  searchResultsOverlayVisible?: boolean;
510
  /** A contextual save bar for the top bar */
511
  contextualSaveBar?: React.ReactNode;
512
  /** Secondary menu for the top bar */
513
  secondaryMenu?: React.ReactNode;
514
  /** Callback when the navigation toggle is clicked */
515
  onNavigationToggle?(): void;
516
}
517
```
518

519
### FullscreenBar
520

521
Fullscreen mode navigation bar that replaces the normal top bar when content is displayed in fullscreen view.
522

523
```typescript { .api }
524
/**
525
 * Navigation bar for fullscreen mode
526
 * @param onAction - Back/exit action handler
527
 * @param children - Content to display in the bar
528
 * @returns JSX element with fullscreen navigation bar
529
 */
530
function FullscreenBar(props: FullscreenBarProps): JSX.Element;
531

532
interface FullscreenBarProps {
533
  /** Callback when the back button is clicked */
534
  onAction(): void;
535
  /** The content to display inside the fullscreen bar */
536
  children?: React.ReactNode;
537
}
538
```