# Core Navigation Components

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

## Capabilities

### NavigationMenu (Root)

The root container component that manages global navigation menu state, timing behavior, and coordinates all child components.

```typescript { .api }
/**
 * Root navigation menu component that manages global state and timing
 * @param value - Controlled value for the currently open menu item
 * @param defaultValue - Default value for uncontrolled mode
 * @param onValueChange - Callback when the active menu item changes
 * @param dir - Text direction, affects keyboard navigation
 * @param orientation - Layout orientation for the menu
 * @param delayDuration - Delay before opening menu on hover (default: 200ms)
 * @param skipDelayDuration - Time window to skip delay when moving between items (default: 300ms)
 */
const NavigationMenu: React.ForwardRefExoticComponent<
  NavigationMenuProps & React.RefAttributes<HTMLElement>
>;

interface NavigationMenuProps extends React.ComponentPropsWithoutRef<"nav"> {
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  dir?: "ltr" | "rtl";
  orientation?: "horizontal" | "vertical";
  delayDuration?: number;
  skipDelayDuration?: number;
}
```

**Usage Examples:**

```typescript
import { NavigationMenu } from "@radix-ui/react-navigation-menu";

// Uncontrolled mode
function UncontrolledNav() {
  return (
    <NavigationMenu defaultValue="home">
      {/* Menu items */}
    </NavigationMenu>
  );
}

// Controlled mode with custom timing
function ControlledNav() {
  const [value, setValue] = React.useState("");
  
  return (
    <NavigationMenu
      value={value}
      onValueChange={setValue}
      delayDuration={100}
      skipDelayDuration={500}
      orientation="vertical"
    >
      {/* Menu items */}
    </NavigationMenu>
  );
}
```

### NavigationMenuList

Container component for navigation menu items, providing the list structure and handling focus management.

```typescript { .api }
/**
 * List container for navigation menu items with focus management
 * Renders as an unordered list (ul) element
 */
const NavigationMenuList: React.ForwardRefExoticComponent<
  NavigationMenuListProps & React.RefAttributes<HTMLUListElement>
>;

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

**Usage Examples:**

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

function NavWithList() {
  return (
    <NavigationMenu>
      <NavigationMenuList className="nav-list">
        <NavigationMenuItem>Item 1</NavigationMenuItem>
        <NavigationMenuItem>Item 2</NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

### NavigationMenuItem

Wrapper component for individual menu items that manages the relationship between triggers and content panels.

```typescript { .api }
/**
 * Individual menu item wrapper that manages trigger-content relationships
 * @param value - Unique identifier for this menu item (auto-generated if not provided)
 */
const NavigationMenuItem: React.ForwardRefExoticComponent<
  NavigationMenuItemProps & React.RefAttributes<HTMLLIElement>
>;

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

**Usage Examples:**

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

function ItemExample() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        {/* Item with explicit value */}
        <NavigationMenuItem value="products">
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            Product content here
          </NavigationMenuContent>
        </NavigationMenuItem>
        
        {/* Item with auto-generated value */}
        <NavigationMenuItem>
          <NavigationMenuTrigger>Services</NavigationMenuTrigger>
          <NavigationMenuContent>
            Service content here
          </NavigationMenuContent>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

### NavigationMenuSub

Sub-navigation container for creating nested menu structures within a parent navigation menu.

```typescript { .api }
/**
 * Sub-navigation container for nested menu structures
 * @param value - Controlled value for the sub-menu
 * @param defaultValue - Default value for uncontrolled sub-menu
 * @param onValueChange - Callback when sub-menu value changes
 * @param orientation - Layout orientation for the sub-menu
 */
const NavigationMenuSub: React.ForwardRefExoticComponent<
  NavigationMenuSubProps & React.RefAttributes<HTMLDivElement>
>;

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

**Usage Examples:**

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

function NestedMenuExample() {
  return (
    <NavigationMenu>
      <NavigationMenuList>
        <NavigationMenuItem>
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
          <NavigationMenuContent>
            <NavigationMenuSub>
              <NavigationMenuList>
                <NavigationMenuItem>
                  <NavigationMenuTrigger>Web Tools</NavigationMenuTrigger>
                  <NavigationMenuContent>
                    Web tools content
                  </NavigationMenuContent>
                </NavigationMenuItem>
              </NavigationMenuList>
            </NavigationMenuSub>
          </NavigationMenuContent>
        </NavigationMenuItem>
      </NavigationMenuList>
    </NavigationMenu>
  );
}
```

## Data Attributes

Core components expose data attributes for styling:

### NavigationMenu Data Attributes

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

### NavigationMenuList Data Attributes

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

### NavigationMenuSub Data Attributes

```css
[data-orientation="horizontal"] { /* Horizontal sub-menu */ }
[data-orientation="vertical"] { /* Vertical sub-menu */ }
```

**Styling Examples:**

```css
.nav-menu[data-orientation="horizontal"] {
  display: flex;
  flex-direction: row;
}

.nav-menu[data-orientation="vertical"] {
  display: flex;
  flex-direction: column;
}

.nav-list[data-orientation="horizontal"] {
  display: flex;
  flex-direction: row;
  gap: 1rem;
}

.nav-list[data-orientation="vertical"] {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}
```