# Radix UI Navigation Menu

Radix UI Navigation Menu is a comprehensive React component library that provides accessible, unstyled navigation menu primitives for building complex website navigation systems. It supports keyboard navigation, focus management, nested menus, and includes a full suite of composable components for creating sophisticated navigation experiences with complete design flexibility.

## Package Information

- **Package Name**: @radix-ui/react-navigation-menu
- **Package Type**: npm  
- **Language**: TypeScript
- **Installation**: `npm install @radix-ui/react-navigation-menu`

## Core Imports

```typescript
import {
  NavigationMenu,
  NavigationMenuSub,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuLink,
  NavigationMenuIndicator,
  NavigationMenuViewport,
  createNavigationMenuScope,
} from "@radix-ui/react-navigation-menu";
```

Alternative short aliases:

```typescript
import {
  Root,
  Sub,
  List,
  Item,
  Trigger,
  Content,
  Link,
  Indicator,
  Viewport,
} from "@radix-ui/react-navigation-menu";
```

**Alias Mappings:**
- `Root` → `NavigationMenu`
- `Sub` → `NavigationMenuSub`
- `List` → `NavigationMenuList`
- `Item` → `NavigationMenuItem`
- `Trigger` → `NavigationMenuTrigger`
- `Content` → `NavigationMenuContent`
- `Link` → `NavigationMenuLink`
- `Indicator` → `NavigationMenuIndicator`
- `Viewport` → `NavigationMenuViewport`

## Basic Usage

```typescript
import React from "react";
import {
  NavigationMenu,
  NavigationMenuList,
  NavigationMenuItem,
  NavigationMenuTrigger,
  NavigationMenuContent,
  NavigationMenuLink,
} from "@radix-ui/react-navigation-menu";

function NavExample() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            <NavigationMenuLink href="/products/web">Web</NavigationMenuLink>
            <NavigationMenuLink href="/products/mobile">Mobile</NavigationMenuLink>
          </NavigationMenuContent>
        </NavigationMenuItem>
        
        <NavigationMenuItem>
          <NavigationMenuLink href="/about">About</NavigationMenuLink>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

## Architecture

The Navigation Menu is built around a hierarchical component system:

- **Root Container**: `NavigationMenu` manages global state, timing, and coordination
- **List Structure**: `NavigationMenuList` provides the container for menu items
- **Item Management**: `NavigationMenuItem` wraps each menu item and manages trigger-content relationships
- **Interactive Elements**: `NavigationMenuTrigger` and `NavigationMenuLink` handle user interactions
- **Content Display**: `NavigationMenuContent` provides dismissable content panels
- **Visual Feedback**: `NavigationMenuIndicator` shows active states
- **Viewport Mode**: `NavigationMenuViewport` enables centralized content rendering
- **Focus Management**: Built-in keyboard navigation and accessibility features
- **State Management**: Controlled/uncontrolled modes with event callbacks

## Capabilities

### Core Navigation Components

Essential components for building navigation menu structures with proper hierarchy and state management.

```typescript { .api }
const NavigationMenu: React.ForwardRefExoticComponent<
  NavigationMenuProps & React.RefAttributes<HTMLElement>
>;

const NavigationMenuList: React.ForwardRefExoticComponent<
  NavigationMenuListProps & React.RefAttributes<HTMLUListElement>
>;

const NavigationMenuItem: React.ForwardRefExoticComponent<
  NavigationMenuItemProps & React.RefAttributes<HTMLLIElement>
>;
```

[Core Components](./core-components.md)

### Interactive Elements

Trigger and link components that handle user interactions with keyboard and pointer support.

```typescript { .api }
const NavigationMenuTrigger: React.ForwardRefExoticComponent<
  NavigationMenuTriggerProps & React.RefAttributes<HTMLButtonElement>
>;

const NavigationMenuLink: React.ForwardRefExoticComponent<
  NavigationMenuLinkProps & React.RefAttributes<HTMLAnchorElement>
>;
```

[Interactive Elements](./interactive-elements.md)

### Content Management

Content and viewport components for displaying menu content with animation support and focus management.

```typescript { .api }
const NavigationMenuContent: React.ForwardRefExoticComponent<
  NavigationMenuContentProps & React.RefAttributes<HTMLDivElement>
>;

const NavigationMenuViewport: React.ForwardRefExoticComponent<
  NavigationMenuViewportProps & React.RefAttributes<HTMLDivElement>
>;
```

[Content Management](./content-management.md)

### Visual Indicators and Sub-menus

Indicator component for visual feedback and sub-menu support for nested navigation structures.

```typescript { .api }
const NavigationMenuIndicator: React.ForwardRefExoticComponent<
  NavigationMenuIndicatorProps & React.RefAttributes<HTMLDivElement>
>;

const NavigationMenuSub: React.ForwardRefExoticComponent<
  NavigationMenuSubProps & React.RefAttributes<HTMLDivElement>
>;
```

[Visual Indicators and Sub-menus](./indicators-submenus.md)

### Utility Functions

Scope creation utility for isolated navigation menu contexts.

```typescript { .api }
function createNavigationMenuScope(): {
  NavigationMenuProvider: React.Provider<any>;
  useNavigationMenuContext: () => any;
};
```

[Utility Functions](./utility-functions.md)

## Types

### Base Props Types

```typescript { .api }
interface NavigationMenuProps extends React.ComponentPropsWithoutRef<"nav"> {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  dir?: "ltr" | "rtl";
  orientation?: "horizontal" | "vertical";
  /**
   * The duration from when the pointer enters the trigger until the tooltip gets opened.
   * @defaultValue 200
   */
  delayDuration?: number;
  /**
   * How much time a user has to enter another trigger without incurring a delay again.
   * @defaultValue 300
   */
  skipDelayDuration?: number;
}

interface NavigationMenuListProps 
  extends React.ComponentPropsWithoutRef<"ul"> {}

interface NavigationMenuItemProps 
  extends React.ComponentPropsWithoutRef<"li"> {
  value?: string;
}

interface NavigationMenuTriggerProps 
  extends React.ComponentPropsWithoutRef<"button"> {}

interface NavigationMenuLinkProps 
  extends Omit<React.ComponentPropsWithoutRef<"a">, "onSelect"> {
  active?: boolean;
  onSelect?: (event: Event) => void;
}
```

### Advanced Props Types

```typescript { .api }
interface NavigationMenuContentProps 
  extends React.ComponentPropsWithoutRef<"div"> {
  forceMount?: true;
}

interface NavigationMenuIndicatorProps 
  extends React.ComponentPropsWithoutRef<"div"> {
  forceMount?: true;
}

interface NavigationMenuViewportProps 
  extends React.ComponentPropsWithoutRef<"div"> {
  forceMount?: true;
}

interface NavigationMenuSubProps 
  extends React.ComponentPropsWithoutRef<"div"> {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  orientation?: "horizontal" | "vertical";
}
```

## Data Attributes

All navigation menu components expose data attributes for styling and state indication:

```css
/* NavigationMenu */
[data-orientation="horizontal"] { /* horizontal layout */ }
[data-orientation="vertical"] { /* vertical layout */ }

/* NavigationMenuTrigger */
[data-state="open"] { /* trigger is active/open */ }
[data-state="closed"] { /* trigger is inactive/closed */ }
[data-disabled] { /* trigger is disabled */ }

/* NavigationMenuContent */
[data-state="open"] { /* content is visible */ }
[data-state="closed"] { /* content is hidden */ }
[data-motion="from-start"] { /* content animating from start */ }
[data-motion="from-end"] { /* content animating from end */ }
[data-motion="to-start"] { /* content animating to start */ }
[data-motion="to-end"] { /* content animating to end */ }
[data-orientation="horizontal"|"vertical"] { /* content orientation */ }

/* NavigationMenuIndicator */
[data-state="visible"] { /* indicator is shown */ }
[data-state="hidden"] { /* indicator is hidden */ }
[data-orientation="horizontal"|"vertical"] { /* indicator orientation */ }

/* NavigationMenuViewport */
[data-state="open"] { /* viewport has content */ }
[data-state="closed"] { /* viewport is empty */ }
[data-orientation="horizontal"|"vertical"] { /* viewport orientation */ }

/* NavigationMenuLink */
[data-active] { /* link represents current page */ }
```