0
# Navigation Components
1

2
Navigation components for building consistent wayfinding experiences including vertical navigation, breadcrumbs, command bars, and pivot tabs for organizing application structure and user flows.
3

4
## Capabilities
5

6
### CommandBar
7

8
Horizontal action bar component for displaying primary commands and overflow menus in applications.
9

10
```typescript { .api }
11
/**
12
 * Horizontal command bar for primary actions and overflow menus
13
 */
14
function CommandBar(props: ICommandBarProps): JSX.Element;
15

16
interface ICommandBar {
17
  /** Focus on the command bar */
18
  focus(): void;
19
}
20

21
interface ICommandBarProps {
22
  /** Reference to access component methods */
23
  componentRef?: IRefObject<ICommandBar>;
24
  /** Primary command items */
25
  items: ICommandBarItemProps[];
26
  /** Items that appear in the overflow menu */
27
  overflowItems?: ICommandBarItemProps[];
28
  /** Items that appear on the far side (right in LTR) */
29
  farItems?: ICommandBarItemProps[];
30
  /** Properties for the overflow button */
31
  overflowButtonProps?: IButtonProps;
32
  /** Aria label for the overflow button ellipsis */
33
  elippsisAriaLabel?: string;
34
  /** Aria label for the command bar */
35
  ariaLabel?: string;
36
  /** Custom render function for data */
37
  onDataReduced?: (movedItem: ICommandBarItemProps) => void;
38
  /** Custom render function for data grown */
39
  onDataGrown?: (movedItem: ICommandBarItemProps) => void;
40
  /** Custom render function for overflow button */
41
  onRenderOverflowButton?: IRenderFunction<IOverflowButtonProps>;
42
  /** Custom styles */
43
  styles?: IStyleFunctionOrObject<ICommandBarStyleProps, ICommandBarStyles>;
44
  /** Theme provided by higher-order component */
45
  theme?: ITheme;
46
  /** Additional CSS class */
47
  className?: string;
48
  /** Shift focus on reduce */
49
  shiftOnReduce?: boolean;
50
}
51

52
interface ICommandBarItemProps extends IContextualMenuItem {
53
  /** Unique cache key for rendering optimization */
54
  cacheKey?: string;
55
  /** Whether the item is rendered in overflow menu */
56
  renderedInOverflow?: boolean;
57
  /** Whether to show only icon (no text) */
58
  iconOnly?: boolean;
59
  /** Custom styles for the button */
60
  buttonStyles?: Partial<IButtonStyles>;
61
  /** Custom render function for the item */
62
  onRender?: (item: ICommandBarItemProps) => React.ReactNode;
63
  /** Properties for the command bar item */
64
  commandBarButtonProps?: ICommandBarItemProps;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import React from "react";
72
import { CommandBar, ICommandBarItemProps } from "office-ui-fabric-react";
73

74
function BasicCommandBar() {
75
  const items: ICommandBarItemProps[] = [
76
    {
77
      key: "new",
78
      text: "New",
79
      iconProps: { iconName: "Add" },
80
      onClick: () => console.log("New clicked"),
81
      subMenuProps: {
82
        items: [
83
          {
84
            key: "newDocument",
85
            text: "Document",
86
            iconProps: { iconName: "WordDocument" },
87
            onClick: () => console.log("New document")
88
          },
89
          {
90
            key: "newSpreadsheet",
91
            text: "Spreadsheet", 
92
            iconProps: { iconName: "ExcelDocument" },
93
            onClick: () => console.log("New spreadsheet")
94
          }
95
        ]
96
      }
97
    },
98
    {
99
      key: "upload",
100
      text: "Upload",
101
      iconProps: { iconName: "Upload" },
102
      onClick: () => console.log("Upload clicked")
103
    },
104
    {
105
      key: "share",
106
      text: "Share",
107
      iconProps: { iconName: "Share" },
108
      onClick: () => console.log("Share clicked")
109
    }
110
  ];
111

112
  const overflowItems: ICommandBarItemProps[] = [
113
    {
114
      key: "export",
115
      text: "Export",
116
      iconProps: { iconName: "Download" },
117
      onClick: () => console.log("Export clicked")
118
    },
119
    {
120
      key: "settings",
121
      text: "Settings",
122
      iconProps: { iconName: "Settings" },
123
      onClick: () => console.log("Settings clicked")
124
    }
125
  ];
126

127
  const farItems: ICommandBarItemProps[] = [
128
    {
129
      key: "search",
130
      text: "Search",
131
      iconProps: { iconName: "Search" },
132
      iconOnly: true,
133
      onClick: () => console.log("Search clicked")
134
    },
135
    {
136
      key: "help",
137
      text: "Help",
138
      iconProps: { iconName: "Help" },
139
      iconOnly: true,
140
      onClick: () => console.log("Help clicked")
141
    }
142
  ];
143

144
  return (
145
    <CommandBar
146
      items={items}
147
      overflowItems={overflowItems}
148
      farItems={farItems}
149
      ariaLabel="Main actions"
150
    />
151
  );
152
}
153
```
154

155
### Nav
156

157
Vertical navigation component for displaying hierarchical navigation structures and links.
158

159
```typescript { .api }
160
/**
161
 * Vertical navigation component for hierarchical navigation
162
 */
163
function Nav(props: INavProps): JSX.Element;
164

165
interface INav {
166
  /** Selected key */
167
  selectedKey: string | undefined;
168
}
169

170
interface INavProps {
171
  /** Reference to access component methods */
172
  componentRef?: IRefObject<INav>;
173
  /** Navigation link groups */
174
  groups?: INavLinkGroup[];
175
  /** Currently selected key */
176
  selectedKey?: string;
177
  /** Initially selected key */
178
  initialSelectedKey?: string;
179
  /** ARIA label for the navigation */
180
  ariaLabel?: string;
181
  /** Whether the navigation is expanded by default */
182
  isOnTop?: boolean;
183
  /** Custom render function for group header */
184
  onRenderGroupHeader?: IRenderFunction<INavLinkGroup>;
185
  /** Custom render function for link */
186
  onRenderLink?: IRenderFunction<INavLink>;
187
  /** Callback fired when link is clicked */
188
  onLinkClick?: (ev?: React.MouseEvent<HTMLElement>, item?: INavLink) => void;
189
  /** Callback fired when group is expanded/collapsed */
190
  onLinkExpandClick?: (ev?: React.MouseEvent<HTMLElement>, item?: INavLink) => void;
191
  /** Custom styles */
192
  styles?: IStyleFunctionOrObject<INavStyleProps, INavStyles>;
193
  /** Theme provided by higher-order component */
194
  theme?: ITheme;
195
  /** Additional CSS class */
196
  className?: string;
197
}
198

199
interface INavLinkGroup {
200
  /** Name of the group */
201
  name?: string;
202
  /** Links in the group */
203
  links: INavLink[];
204
  /** Whether the group is collapsed */
205
  collapseByDefault?: boolean;
206
  /** Custom render function for the group */
207
  onRenderGroupHeader?: IRenderFunction<INavLinkGroup>;
208
}
209

210
interface INavLink {
211
  /** Display name for the link */
212
  name: string;
213
  /** URL for the link */
214
  url?: string;
215
  /** Unique key for the link */
216
  key?: string;
217
  /** Links nested under this link */
218
  links?: INavLink[];
219
  /** Icon to display with the link */
220
  icon?: string;
221
  /** Whether the link is expanded */
222
  isExpanded?: boolean;
223
  /** Whether the link is disabled */
224
  disabled?: boolean;
225
  /** Target for the link */
226
  target?: string;
227
  /** Title attribute */
228
  title?: string;
229
  /** ARIA label */
230
  ariaLabel?: string;
231
  /** Whether to force the link to be an anchor */
232
  forceAnchor?: boolean;
233
  /** Additional data */
234
  [propertyName: string]: any;
235
}
236
```
237

238
**Usage Examples:**
239

240
```typescript
241
import React, { useState } from "react";
242
import { Nav, INavLinkGroup, INavLink } from "office-ui-fabric-react";
243

244
function BasicNav() {
245
  const [selectedKey, setSelectedKey] = useState("dashboard");
246

247
  const navGroups: INavLinkGroup[] = [
248
    {
249
      name: "Main",
250
      links: [
251
        {
252
          name: "Dashboard",
253
          key: "dashboard",
254
          url: "/dashboard",
255
          icon: "ViewDashboard"
256
        },
257
        {
258
          name: "Documents",
259
          key: "documents",
260
          url: "/documents",
261
          icon: "FabricFolder",
262
          links: [
263
            {
264
              name: "Recent",
265
              key: "recent",
266
              url: "/documents/recent"
267
            },
268
            {
269
              name: "Shared",
270
              key: "shared", 
271
              url: "/documents/shared"
272
            }
273
          ]
274
        },
275
        {
276
          name: "People",
277
          key: "people",
278
          url: "/people",
279
          icon: "People"
280
        }
281
      ]
282
    },
283
    {
284
      name: "Settings",
285
      links: [
286
        {
287
          name: "Preferences",
288
          key: "preferences",
289
          url: "/settings/preferences",
290
          icon: "Settings"
291
        },
292
        {
293
          name: "Account",
294
          key: "account",
295
          url: "/settings/account",
296
          icon: "Contact"
297
        }
298
      ]
299
    }
300
  ];
301

302
  return (
303
    <Nav
304
      groups={navGroups}
305
      selectedKey={selectedKey}
306
      onLinkClick={(ev, item) => {
307
        if (item) {
308
          setSelectedKey(item.key || "");
309
          console.log("Navigate to:", item.url);
310
        }
311
      }}
312
      ariaLabel="Main navigation"
313
    />
314
  );
315
}
316
```
317

318
### Breadcrumb
319

320
Hierarchical navigation trail showing the user's current location in the application structure.
321

322
```typescript { .api }
323
/**
324
 * Hierarchical navigation trail component
325
 */
326
function Breadcrumb(props: IBreadcrumbProps): JSX.Element;
327

328
interface IBreadcrumb {
329
  /** Focus on the breadcrumb */
330
  focus(): void;
331
}
332

333
interface IBreadcrumbProps {
334
  /** Reference to access component methods */
335
  componentRef?: IRefObject<IBreadcrumb>;
336
  /** Breadcrumb items to display */
337
  items: IBreadcrumbItem[];
338
  /** Custom render function for each item */
339
  onRenderItem?: IRenderFunction<IBreadcrumbItem>;
340
  /** Custom render function for overflow button */
341
  onRenderOverflowIcon?: IRenderFunction<IBreadcrumbProps>;
342
  /** Divider icon name */
343
  dividerAs?: React.ComponentType<IBreadcrumbProps>;
344
  /** Maximum number of items to display */
345
  maxDisplayedItems?: number;
346
  /** Aria label for the breadcrumb */
347
  ariaLabel?: string;
348
  /** Overflow aria label */
349
  overflowAriaLabel?: string;
350
  /** Overflow index */
351
  overflowIndex?: number;
352
  /** Custom render function for tooltip */
353
  onRenderTooltip?: IRenderFunction<IBreadcrumbItem>;
354
  /** Function to reduce data */
355
  onReduceData?: (data: IBreadcrumbData) => IBreadcrumbData | undefined;
356
  /** Function to grow data */
357
  onGrowData?: (data: IBreadcrumbData) => IBreadcrumbData | undefined;
358
  /** Custom styles */
359
  styles?: IStyleFunctionOrObject<IBreadcrumbStyleProps, IBreadcrumbStyles>;
360
  /** Theme provided by higher-order component */
361
  theme?: ITheme;
362
  /** Additional CSS class */
363
  className?: string;
364
}
365

366
interface IBreadcrumbItem {
367
  /** Display text for the item */
368
  text: string;
369
  /** Unique key for the item */
370
  key: string;
371
  /** Click handler for the item */
372
  onClick?: (ev?: React.MouseEvent<HTMLElement>, item?: IBreadcrumbItem) => void;
373
  /** Href for the item */
374
  href?: string;
375
  /** Whether the item is the current page */
376
  isCurrentItem?: boolean;
377
  /** Custom render function for the item */
378
  onRender?: (item?: IBreadcrumbItem) => React.ReactNode;
379
}
380

381
interface IBreadcrumbData {
382
  /** Breadcrumb items */
383
  items: IBreadcrumbItem[];
384
  /** Maximum displayed items */
385
  maxDisplayedItems: number;
386
}
387
```
388

389
### Pivot
390

391
Tab-like navigation component for organizing content into related sections.
392

393
```typescript { .api }
394
/**
395
 * Tab-like navigation component for content organization
396
 */
397
function Pivot(props: IPivotProps): JSX.Element;
398

399
/**
400
 * Individual pivot section
401
 */
402
function PivotItem(props: IPivotItemProps): JSX.Element;
403

404
interface IPivot {
405
  /** Focus on the pivot */
406
  focus(): void;
407
}
408

409
interface IPivotProps {
410
  /** Reference to access component methods */
411
  componentRef?: IRefObject<IPivot>;
412
  /** Currently selected key */
413
  selectedKey?: string;
414
  /** Default selected key for uncontrolled usage */
415
  defaultSelectedKey?: string;
416
  /** Display format for pivot links */
417
  linkFormat?: PivotLinkFormat;
418
  /** Size of pivot links */
419
  linkSize?: PivotLinkSize;
420
  /** Whether to render only headers without content */
421
  headersOnly?: boolean;
422
  /** Function to get tab ID */
423
  getTabId?: (itemKey: string, index: number) => string;
424
  /** Custom render function for pivot link */
425
  onRenderLink?: (link?: IPivotItemProps, defaultRenderer?: (link?: IPivotItemProps) => React.ReactNode) => React.ReactNode;
426
  /** Callback fired when pivot link is clicked */
427
  onLinkClick?: (item?: PivotItem, ev?: React.MouseEvent<HTMLElement>) => void;
428
  /** Custom styles */
429
  styles?: IStyleFunctionOrObject<IPivotStyleProps, IPivotStyles>;
430
  /** Theme provided by higher-order component */
431
  theme?: ITheme;
432
  /** Additional CSS class */
433
  className?: string;
434
  /** Child PivotItem elements */
435
  children?: React.ReactNode;
436
}
437

438
interface IPivotItemProps {
439
  /** Reference to access component methods */
440
  componentRef?: IRefObject<IPivotItem>;
441
  /** Display text for the pivot item */
442
  headerText?: string;
443
  /** Button properties for the header */
444
  headerButtonProps?: IButtonProps | { [key: string]: string | number | boolean };
445
  /** Unique key identifying the pivot item */
446
  itemKey?: string;
447
  /** ARIA label for the pivot item */
448
  ariaLabel?: string;
449
  /** Count to display in the header */
450
  itemCount?: number | string;
451
  /** Icon to display in the header */
452
  itemIcon?: string;
453
  /** Key tips properties */
454
  keytipProps?: IKeytipProps;
455
  /** Link format override for this item */
456
  linkFormat?: PivotLinkFormat;
457
  /** Custom render function for the header */
458
  onRenderItemLink?: (props?: IPivotItemProps, defaultRender?: (props?: IPivotItemProps) => React.ReactNode) => React.ReactNode;
459
  /** Additional CSS class */
460
  className?: string;
461
  /** Child content for the pivot item */
462
  children?: React.ReactNode;
463
}
464

465
enum PivotLinkFormat {
466
  links = 0,
467
  tabs = 1
468
}
469

470
enum PivotLinkSize {
471
  normal = 0,
472
  large = 1
473
}
474
```
475

476
**Usage Examples:**
477

478
```typescript
479
import React, { useState } from "react";
480
import { Pivot, PivotItem, PivotLinkFormat, PivotLinkSize } from "office-ui-fabric-react";
481

482
function BasicPivot() {
483
  return (
484
    <Pivot>
485
      <PivotItem headerText="Overview" itemKey="overview">
486
        <div>Overview content goes here</div>
487
      </PivotItem>
488
      
489
      <PivotItem headerText="Details" itemKey="details" itemCount={5}>
490
        <div>Details content with 5 items</div>
491
      </PivotItem>
492
      
493
      <PivotItem headerText="Settings" itemKey="settings" itemIcon="Settings">
494
        <div>Settings content with icon</div>
495
      </PivotItem>
496
    </Pivot>
497
  );
498
}
499

500
function ControlledPivot() {
501
  const [selectedKey, setSelectedKey] = useState("tab1");
502

503
  return (
504
    <Pivot
505
      selectedKey={selectedKey}
506
      onLinkClick={(item) => {
507
        if (item?.props.itemKey) {
508
          setSelectedKey(item.props.itemKey);
509
        }
510
      }}
511
      linkFormat={PivotLinkFormat.tabs}
512
      linkSize={PivotLinkSize.large}
513
    >
514
      <PivotItem headerText="First Tab" itemKey="tab1">
515
        <div>Content for first tab</div>
516
      </PivotItem>
517
      
518
      <PivotItem headerText="Second Tab" itemKey="tab2">
519
        <div>Content for second tab</div>
520
      </PivotItem>
521
      
522
      <PivotItem headerText="Third Tab" itemKey="tab3">
523
        <div>Content for third tab</div>
524
      </PivotItem>
525
    </Pivot>
526
  );
527
}
528
```
529

530
## Types
531

532
```typescript { .api }
533
// Common navigation interfaces
534
interface IContextualMenuItem {
535
  /** Unique key for the item */
536
  key: string;
537
  /** Display text */
538
  text?: string;
539
  /** Secondary text */
540
  secondaryText?: string;
541
  /** Item type (normal, divider, header, section) */
542
  itemType?: ContextualMenuItemType;
543
  /** Icon properties */
544
  iconProps?: IIconProps;
545
  /** Submenu items */
546
  subMenuProps?: IContextualMenuProps;
547
  /** Whether the item is disabled */
548
  disabled?: boolean;
549
  /** Whether the item is checked */
550
  checked?: boolean;
551
  /** Whether the item can be checked */
552
  canCheck?: boolean;
553
  /** Whether the item is split */
554
  split?: boolean;
555
  /** Additional data */
556
  data?: any;
557
  /** Click handler */
558
  onClick?: (ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, item?: IContextualMenuItem) => boolean | void;
559
  /** Custom render function */
560
  onRender?: (item: IContextualMenuItem, dismissMenu: (ev?: any, dismissAll?: boolean) => void) => React.ReactNode;
561
  /** ARIA label */
562
  ariaLabel?: string;
563
  /** Title attribute */
564
  title?: string;
565
  /** CSS class name */
566
  className?: string;
567
  /** Custom styles */
568
  style?: React.CSSProperties;
569
  /** HTML role */
570
  role?: string;
571
  /** Primary disabled state (for split items) */
572
  primaryDisabled?: boolean;
573
  /** Short name */
574
  shortName?: string;
575
}
576

577
enum ContextualMenuItemType {
578
  Normal = 0,
579
  Divider = 1,
580
  Header = 2,
581
  Section = 3
582
}
583

584
// Button interfaces for navigation components
585
interface IButtonProps {
586
  /** Button text */
587
  text?: string;
588
  /** Whether button is primary */
589
  primary?: boolean;
590
  /** Whether button is disabled */
591
  disabled?: boolean;
592
  /** Click handler */
593
  onClick?: (event?: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement | HTMLDivElement>) => void;
594
  /** Icon properties */
595
  iconProps?: IIconProps;
596
  /** Menu properties */
597
  menuProps?: IContextualMenuProps;
598
  /** Custom styles */
599
  styles?: IStyleFunctionOrObject<IButtonStyleProps, IButtonStyles>;
600
  /** Additional CSS class */
601
  className?: string;
602
  /** ARIA label */
603
  ariaLabel?: string;
604
}
605

606
// Render function interface
607
interface IRenderFunction<TProps> {
608
  (props?: TProps, defaultRender?: (props?: TProps) => React.ReactNode | null): React.ReactNode | null;
609
}
610
```