0
# Navigation Components
1

2
NextUI's navigation components provide comprehensive solutions for website navigation, hierarchical content organization, and user interface routing patterns.
3

4
## Capabilities
5

6
### Navbar
7

8
A responsive navigation bar component that adapts to different screen sizes with support for branding, navigation items, and mobile menu functionality.
9

10
```typescript { .api }
11
interface NavbarProps {
12
  /** Navbar content including brand, items, and menu */
13
  children?: React.ReactNode;
14
  /** Fixed height of the navbar */
15
  height?: string | number;
16
  /** Maximum width constraint */
17
  maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl" | "full";
18
  /** Positioning behavior */
19
  position?: "static" | "sticky";
20
  /** Add bottom border */
21
  isBordered?: boolean;
22
  /** Apply blur backdrop effect */
23
  isBlurred?: boolean;
24
  /** Hide navbar when scrolling down */
25
  shouldHideOnScroll?: boolean;
26
  /** Custom CSS class */
27
  className?: string;
28
  /** Slot-based styling */
29
  classNames?: SlotsToClasses<NavbarSlots>;
30
  /** Parent scroll reference for hide behavior */
31
  parentRef?: React.RefObject<HTMLElement>;
32
  /** Scroll event handler */
33
  onScrollPositionChange?: (scrollPosition: number) => void;
34
}
35

36
type NavbarSlots = 
37
  | "base" | "wrapper" | "brand" | "content" 
38
  | "item" | "toggle" | "toggleIcon" | "menu" | "menuItem";
39

40
function Navbar(props: NavbarProps): JSX.Element;
41

42
/**
43
 * Hook for Navbar state management
44
 */
45
function useNavbar(props: NavbarProps): {
46
  Component: React.ElementType;
47
  slots: Record<NavbarSlots, string>;
48
  classNames: SlotsToClasses<NavbarSlots>;
49
  hideOnScroll: boolean;
50
  shouldHide: boolean;
51
  height: string | number;
52
  getNavbarProps: () => any;
53
};
54
```
55

56
### Navbar Sections
57

58
Specialized components for organizing navbar content.
59

60
```typescript { .api }
61
interface NavbarBrandProps {
62
  /** Brand content (logo, title, etc.) */
63
  children?: React.ReactNode;
64
  /** Custom CSS class */
65
  className?: string;
66
}
67

68
interface NavbarContentProps {
69
  /** Navigation content */
70
  children?: React.ReactNode;
71
  /** Content justification */
72
  justify?: "start" | "center" | "end";
73
  /** Custom CSS class */
74
  className?: string;
75
}
76

77
interface NavbarItemProps {
78
  /** Item content */
79
  children?: React.ReactNode;
80
  /** Whether item is currently active */
81
  isActive?: boolean;
82
  /** Custom CSS class */
83
  className?: string;
84
}
85

86
interface NavbarMenuToggleProps {
87
  /** Toggle icon element */
88
  icon?: React.ReactNode;
89
  /** Whether menu is open */
90
  isSelected?: boolean;
91
  /** Custom CSS class */
92
  className?: string;
93
  /** Change handler for toggle state */
94
  onChange?: (isSelected: boolean) => void;
95
}
96

97
interface NavbarMenuProps {
98
  /** Menu items */
99
  children?: React.ReactNode;
100
  /** Custom CSS class */
101
  className?: string;
102
  /** Portal container for menu */
103
  portalContainer?: Element;
104
}
105

106
interface NavbarMenuItemProps {
107
  /** Menu item content */
108
  children?: React.ReactNode;
109
  /** Custom CSS class */
110
  className?: string;
111
}
112

113
function NavbarBrand(props: NavbarBrandProps): JSX.Element;
114
function NavbarContent(props: NavbarContentProps): JSX.Element;
115
function NavbarItem(props: NavbarItemProps): JSX.Element;
116
function NavbarMenuToggle(props: NavbarMenuToggleProps): JSX.Element;
117
function NavbarMenu(props: NavbarMenuProps): JSX.Element;
118
function NavbarMenuItem(props: NavbarMenuItemProps): JSX.Element;
119
```
120

121
**Navbar Usage Example:**
122

123
```typescript
124
import { 
125
  Navbar, NavbarBrand, NavbarContent, NavbarItem, NavbarMenuToggle,
126
  NavbarMenu, NavbarMenuItem, Button, Link
127
} from "@nextui-org/react";
128
import { useState } from "react";
129

130
function AppNavbar() {
131
  const [isMenuOpen, setIsMenuOpen] = useState(false);
132

133
  const menuItems = [
134
    "Profile", "Dashboard", "Activity", "Analytics", "System", "Deployments"
135
  ];
136

137
  return (
138
    <Navbar 
139
      onMenuOpenChange={setIsMenuOpen}
140
      isBlurred
141
      isBordered
142
      maxWidth="xl"
143
    >
144
      <NavbarContent>
145
        <NavbarMenuToggle
146
          aria-label={isMenuOpen ? "Close menu" : "Open menu"}
147
          className="sm:hidden"
148
        />
149
        <NavbarBrand>
150
          <p className="font-bold text-inherit">ACME</p>
151
        </NavbarBrand>
152
      </NavbarContent>
153

154
      <NavbarContent className="hidden sm:flex gap-4" justify="center">
155
        <NavbarItem>
156
          <Link color="foreground" href="#">Features</Link>
157
        </NavbarItem>
158
        <NavbarItem isActive>
159
          <Link href="#" aria-current="page">Customers</Link>
160
        </NavbarItem>
161
        <NavbarItem>
162
          <Link color="foreground" href="#">Integrations</Link>
163
        </NavbarItem>
164
      </NavbarContent>
165
      
166
      <NavbarContent justify="end">
167
        <NavbarItem className="hidden lg:flex">
168
          <Link href="#">Login</Link>
169
        </NavbarItem>
170
        <NavbarItem>
171
          <Button as={Link} color="primary" href="#" variant="flat">
172
            Sign Up
173
          </Button>
174
        </NavbarItem>
175
      </NavbarContent>
176
      
177
      <NavbarMenu>
178
        {menuItems.map((item, index) => (
179
          <NavbarMenuItem key={`${item}-${index}`}>
180
            <Link
181
              color={
182
                index === 2 ? "primary" : index === menuItems.length - 1 ? "danger" : "foreground"
183
              }
184
              className="w-full"
185
              href="#"
186
              size="lg"
187
            >
188
              {item}
189
            </Link>
190
          </NavbarMenuItem>
191
        ))}
192
      </NavbarMenu>
193
    </Navbar>
194
  );
195
}
196
```
197

198
### Navbar Context
199

200
Context system for sharing navbar state across navbar components.
201

202
```typescript { .api }
203
interface NavbarProviderProps {
204
  children: React.ReactNode;
205
  value: NavbarContextValue;
206
}
207

208
interface NavbarContextValue {
209
  slots: Record<NavbarSlots, string>;
210
  classNames?: SlotsToClasses<NavbarSlots>;
211
  height?: string | number;
212
  isMenuOpen?: boolean;
213
  shouldHideOnScroll?: boolean;
214
  hideOnScroll?: boolean;
215
  maxWidth?: string;
216
}
217

218
const NavbarProvider: React.FC<NavbarProviderProps>;
219

220
/**
221
 * Hook to access navbar context
222
 * @throws Error if used outside NavbarProvider
223
 */
224
function useNavbarContext(): NavbarContextValue;
225
```
226

227
### Breadcrumbs
228

229
A navigation component that shows the user's current location within a hierarchical structure.
230

231
```typescript { .api }
232
interface BreadcrumbsProps {
233
  /** Breadcrumb items */
234
  children: React.ReactNode;
235
  /** Custom separator between items */
236
  separator?: React.ReactNode;
237
  /** Size variant */
238
  size?: "sm" | "md" | "lg";
239
  /** Border radius */
240
  radius?: "none" | "sm" | "md" | "lg" | "full";
241
  /** Visual variant */
242
  variant?: "solid" | "bordered" | "light";
243
  /** Color theme */
244
  color?: "foreground" | "primary" | "secondary" | "success" | "warning" | "danger";
245
  /** Text underline behavior */
246
  underline?: "none" | "hover" | "always" | "active" | "focus";
247
  /** Hide the separator */
248
  hideSeparator?: boolean;
249
  /** Disable all breadcrumbs */
250
  isDisabled?: boolean;
251
  /** Disable animations */
252
  disableAnimation?: boolean;
253
  /** Maximum items to show before truncation */
254
  maxItems?: number;
255
  /** Items to show at start when truncated */
256
  itemsBeforeCollapse?: number;
257
  /** Items to show at end when truncated */
258
  itemsAfterCollapse?: number;
259
  /** Render function for overflow menu */
260
  renderEllipsis?: (items: React.ReactNode[]) => React.ReactNode;
261
  /** Custom CSS class */
262
  className?: string;
263
  /** Slot-based styling */
264
  classNames?: SlotsToClasses<BreadcrumbsSlots>;
265
}
266

267
type BreadcrumbsSlots = "base" | "list" | "ellipsis" | "separator";
268

269
function Breadcrumbs(props: BreadcrumbsProps): JSX.Element;
270

271
/**
272
 * Hook for Breadcrumbs state management
273
 */
274
function useBreadcrumbs(props: BreadcrumbsProps): {
275
  Component: React.ElementType;
276
  slots: Record<BreadcrumbsSlots, string>;
277
  classNames: SlotsToClasses<BreadcrumbsSlots>;
278
  getBreadcrumbsProps: () => any;
279
};
280
```
281

282
### Breadcrumb Item
283

284
Individual breadcrumb items with support for links and current page indication.
285

286
```typescript { .api }
287
interface BreadcrumbItemProps {
288
  /** Item content */
289
  children?: React.ReactNode;
290
  /** Whether this is the current page */
291
  isCurrent?: boolean;
292
  /** Whether item is disabled */
293
  isDisabled?: boolean;
294
  /** Link href for navigation */
295
  href?: string;
296
  /** Custom CSS class */
297
  className?: string;
298
  /** Click event handler */
299
  onPress?: () => void;
300
}
301

302
function BreadcrumbItem(props: BreadcrumbItemProps): JSX.Element;
303

304
/**
305
 * Hook for BreadcrumbItem state management
306
 */
307
function useBreadcrumbItem(props: BreadcrumbItemProps): {
308
  Component: React.ElementType;
309
  getBreadcrumbItemProps: () => any;
310
  isCurrent: boolean;
311
  isDisabled: boolean;
312
};
313
```
314

315
**Breadcrumbs Usage Example:**
316

317
```typescript
318
import { Breadcrumbs, BreadcrumbItem } from "@nextui-org/react";
319

320
function NavigationBreadcrumbs() {
321
  return (
322
    <Breadcrumbs 
323
      size="lg" 
324
      color="primary"
325
      underline="hover"
326
      maxItems={4}
327
      itemsBeforeCollapse={1}
328
      itemsAfterCollapse={2}
329
    >
330
      <BreadcrumbItem href="/">Home</BreadcrumbItem>
331
      <BreadcrumbItem href="/products">Products</BreadcrumbItem>
332
      <BreadcrumbItem href="/products/electronics">Electronics</BreadcrumbItem>
333
      <BreadcrumbItem href="/products/electronics/phones">Phones</BreadcrumbItem>
334
      <BreadcrumbItem isCurrent>iPhone 15 Pro</BreadcrumbItem>
335
    </Breadcrumbs>
336
  );
337
}
338
```
339

340
### Tabs
341

342
A tab component for organizing content into separate views with keyboard navigation and accessibility support.
343

344
```typescript { .api }
345
interface TabsProps {
346
  /** Tab items */
347
  children?: React.ReactNode;
348
  /** Tab variant style */
349
  variant?: "solid" | "underlined" | "bordered" | "light";
350
  /** Color theme */
351
  color?: "default" | "primary" | "secondary" | "success" | "warning" | "danger";
352
  /** Size variant */
353
  size?: "sm" | "md" | "lg";
354
  /** Border radius */
355
  radius?: "none" | "sm" | "md" | "lg" | "full";
356
  /** Cursor style for tab selection */
357
  cursor?: "default" | "pointer";
358
  /** Tab selection behavior */
359
  selectionMode?: "single" | "multiple";
360
  /** Currently selected keys */
361
  selectedKey?: React.Key;
362
  /** Default selected key for uncontrolled mode */
363
  defaultSelectedKey?: React.Key;
364
  /** All selected keys for multiple selection */
365
  selectedKeys?: Selection;
366
  /** Default selected keys for multiple selection */
367
  defaultSelectedKeys?: Selection;
368
  /** Disable empty selection */
369
  disallowEmptySelection?: boolean;
370
  /** Whether tabs should take full width */
371
  fullWidth?: boolean;
372
  /** Placement of tabs relative to content */
373
  placement?: "top" | "bottom" | "start" | "end";
374
  /** Whether tabs are keyboard focusable */
375
  isKeyboardActivationDisabled?: boolean;
376
  /** Disable all tabs */
377
  isDisabled?: boolean;
378
  /** Disable animations */
379
  disableAnimation?: boolean;
380
  /** Disable cursor animation */
381
  disableCursorAnimation?: boolean;
382
  /** Custom CSS class */
383
  className?: string;
384
  /** Slot-based styling */
385
  classNames?: SlotsToClasses<TabsSlots>;
386
  /** Selection change handler */
387
  onSelectionChange?: (key: React.Key) => void;
388
}
389

390
type TabsSlots = 
391
  | "base" | "tabList" | "tab" | "tabContent" 
392
  | "cursor" | "panel" | "wrapper";
393

394
function Tabs(props: TabsProps): JSX.Element;
395

396
/**
397
 * Hook for Tabs state management
398
 */
399
function useTabs(props: TabsProps): {
400
  Component: React.ElementType;
401
  slots: Record<TabsSlots, string>;
402
  classNames: SlotsToClasses<TabsSlots>;
403
  getTabsProps: () => any;
404
  getTabListProps: () => any;
405
};
406
```
407

408
### Tab Item
409

410
Individual tab item component for use within Tabs.
411

412
```typescript { .api }
413
interface TabItemProps {
414
  /** Tab key identifier */
415
  key?: React.Key;
416
  /** Tab title */
417
  title?: React.ReactNode;
418
  /** Tab content */
419
  children?: React.ReactNode;
420
  /** Whether tab is disabled */
421
  isDisabled?: boolean;
422
  /** Custom title content with full control */
423
  titleValue?: React.ReactNode;
424
  /** Custom CSS class */
425
  className?: string;
426
}
427

428
function Tab(props: TabItemProps): JSX.Element;
429
```
430

431
**Tabs Usage Example:**
432

433
```typescript
434
import { Tabs, Tab, Card, CardBody } from "@nextui-org/react";
435

436
function ProductTabs() {
437
  return (
438
    <div className="flex w-full flex-col">
439
      <Tabs 
440
        aria-label="Product options" 
441
        color="primary" 
442
        variant="underlined"
443
        classNames={{
444
          tabList: "gap-6 w-full relative rounded-none p-0 border-b border-divider",
445
          cursor: "w-full bg-[#22d3ee]",
446
          tab: "max-w-fit px-0 h-12",
447
          tabContent: "group-data-[selected=true]:text-[#06b6d4]"
448
        }}
449
      >
450
        <Tab
451
          key="photos"
452
          title={
453
            <div className="flex items-center space-x-2">
454
              <GalleryIcon/>
455
              <span>Photos</span>
456
            </div>
457
          }
458
        >
459
          <Card>
460
            <CardBody>
461
              Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 
462
              eiusmod tempor incididunt ut labore et dolore magna aliqua.
463
            </CardBody>
464
          </Card>  
465
        </Tab>
466
        <Tab
467
          key="music" 
468
          title={
469
            <div className="flex items-center space-x-2">
470
              <MusicIcon/>
471
              <span>Music</span>
472
            </div>
473
          }
474
        >
475
          <Card>
476
            <CardBody>
477
              Ut enim ad minim veniam, quis nostrud exercitation ullamco 
478
              laboris nisi ut aliquip ex ea commodo consequat.
479
            </CardBody>
480
          </Card>  
481
        </Tab>
482
        <Tab
483
          key="videos"
484
          title={
485
            <div className="flex items-center space-x-2">
486
              <VideoIcon/>
487
              <span>Videos</span>  
488
            </div>
489
          }
490
        >
491
          <Card>
492
            <CardBody>
493
              Duis aute irure dolor in reprehenderit in voluptate velit esse 
494
              cillum dolore eu fugiat nulla pariatur.
495
            </CardBody>
496
          </Card>  
497
        </Tab>
498
      </Tabs>
499
    </div>  
500
  );
501
}
502
```
503

504
### Link
505

506
A link component with NextUI theming and routing integration support.
507

508
```typescript { .api }
509
interface LinkProps {
510
  /** Link content */
511
  children?: React.ReactNode;
512
  /** Navigation href */
513
  href?: string;
514
  /** Link target */
515
  target?: "_blank" | "_self" | "_parent" | "_top";
516
  /** Size variant */
517
  size?: "sm" | "md" | "lg";
518
  /** Color theme */
519
  color?: "foreground" | "primary" | "secondary" | "success" | "warning" | "danger";
520
  /** Text underline behavior */
521
  underline?: "none" | "hover" | "always" | "active" | "focus";
522
  /** Whether link is disabled */
523
  isDisabled?: boolean;
524
  /** Whether link opens external content */
525
  isExternal?: boolean;
526
  /** Whether to show external link icon */
527
  showAnchorIcon?: boolean;
528
  /** Custom anchor icon */
529
  anchorIcon?: React.ReactNode;
530
  /** Whether link spans full width */
531
  isBlock?: boolean;
532
  /** Disable animations */
533
  disableAnimation?: boolean;
534
  /** Custom CSS class */
535
  className?: string;
536
  /** Press event handler */
537
  onPress?: () => void;
538
}
539

540
function Link(props: LinkProps): JSX.Element;
541

542
/**
543
 * Hook for Link state management
544
 */
545
function useLink(props: LinkProps): {
546
  Component: React.ElementType;
547
  getLinkProps: () => any;
548
  isExternal: boolean;
549
  showAnchorIcon: boolean;
550
};
551

552
/**
553
 * Link icon component for external links
554
 */
555
interface LinkIconProps {
556
  className?: string;
557
}
558

559
function LinkIcon(props: LinkIconProps): JSX.Element;
560
```
561

562
**Link Usage Examples:**
563

564
```typescript
565
import { Link } from "@nextui-org/react";
566

567
function LinkExamples() {
568
  return (
569
    <div className="space-y-4">
570
      {/* Basic link */}
571
      <Link href="/about">About Us</Link>
572
      
573
      {/* External link with icon */}
574
      <Link 
575
        href="https://nextui.org" 
576
        isExternal 
577
        showAnchorIcon
578
        color="primary"
579
      >
580
        NextUI Documentation
581
      </Link>
582
      
583
      {/* Block link */}
584
      <Link 
585
        href="/contact"
586
        isBlock
587
        color="secondary"
588
        size="lg"
589
        underline="hover"
590
      >
591
        Contact Support
592
      </Link>
593
      
594
      {/* Disabled link */}
595
      <Link href="/coming-soon" isDisabled>
596
        Coming Soon
597
      </Link>
598
    </div>
599
  );
600
}
601
```
602

603
## Navigation Component Types
604

605
```typescript { .api }
606
// Common navigation types
607
type NavigationSize = "sm" | "md" | "lg";
608
type NavigationColor = "foreground" | "primary" | "secondary" | "success" | "warning" | "danger";
609
type UnderlineType = "none" | "hover" | "always" | "active" | "focus";
610

611
// Navbar specific types
612
interface NavbarState {
613
  isMenuOpen: boolean;
614
  shouldHideOnScroll: boolean;
615
  hideOnScroll: boolean;
616
  height: string | number;
617
  maxWidth: string;
618
}
619

620
// Breadcrumbs types
621
interface BreadcrumbsState {
622
  maxItems?: number;
623
  itemsBeforeCollapse?: number;
624
  itemsAfterCollapse?: number;
625
  isCollapsed: boolean;
626
  visibleItems: React.ReactNode[];
627
  collapsedItems: React.ReactNode[];
628
}
629

630
// Tabs types  
631
interface TabsState {
632
  selectedKey?: React.Key;
633
  selectedKeys?: Selection;
634
  disallowEmptySelection?: boolean;
635
  selectionMode?: "single" | "multiple";
636
  orientation: "horizontal" | "vertical";
637
}
638

639
// Link types
640
interface LinkState {
641
  isExternal: boolean;
642
  showAnchorIcon: boolean;
643
  isDisabled: boolean;
644
  href?: string;
645
  target?: string;
646
}
647
```
648

649
## Integration Examples
650

651
### Complete Navigation Setup
652

653
```typescript
654
import { 
655
  Navbar, NavbarBrand, NavbarContent, NavbarItem,
656
  Breadcrumbs, BreadcrumbItem, Tabs, Tab, Link
657
} from "@nextui-org/react";
658

659
function AppLayout({ children }: { children: React.ReactNode }) {
660
  return (
661
    <div className="min-h-screen">
662
      {/* Main navigation */}
663
      <Navbar isBordered maxWidth="2xl">
664
        <NavbarBrand>
665
          <Link href="/" className="font-bold text-inherit">
666
            My App
667
          </Link>
668
        </NavbarBrand>
669
        <NavbarContent className="hidden sm:flex gap-4" justify="center">
670
          <NavbarItem>
671
            <Link href="/products" color="foreground">Products</Link>
672
          </NavbarItem>
673
          <NavbarItem>
674
            <Link href="/services" color="foreground">Services</Link>
675
          </NavbarItem>
676
          <NavbarItem>
677
            <Link href="/about" color="foreground">About</Link>
678
          </NavbarItem>
679
        </NavbarContent>
680
      </Navbar>
681
      
682
      {/* Breadcrumb navigation */}
683
      <div className="p-4 border-b">
684
        <Breadcrumbs>
685
          <BreadcrumbItem href="/">Home</BreadcrumbItem>
686
          <BreadcrumbItem href="/products">Products</BreadcrumbItem>
687
          <BreadcrumbItem isCurrent>Laptops</BreadcrumbItem>
688
        </Breadcrumbs>
689
      </div>
690
      
691
      {/* Content area with tabs */}
692
      <div className="p-4">
693
        {children}
694
      </div>
695
    </div>
696
  );
697
}
698
```