0
# Core Navigation Components
1

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

4
## Capabilities
5

6
### NavigationMenu (Root)
7

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

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

25
interface NavigationMenuProps extends React.ComponentPropsWithoutRef<"nav"> {
26
  value?: string;
27
  defaultValue?: string;
28
  onValueChange?: (value: string) => void;
29
  dir?: "ltr" | "rtl";
30
  orientation?: "horizontal" | "vertical";
31
  delayDuration?: number;
32
  skipDelayDuration?: number;
33
}
34
```
35

36
**Usage Examples:**
37

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

41
// Uncontrolled mode
42
function UncontrolledNav() {
43
  return (
44
    <NavigationMenu defaultValue="home">
45
      {/* Menu items */}
46
    </NavigationMenu>
47
  );
48
}
49

50
// Controlled mode with custom timing
51
function ControlledNav() {
52
  const [value, setValue] = React.useState("");
53
  
54
  return (
55
    <NavigationMenu
56
      value={value}
57
      onValueChange={setValue}
58
      delayDuration={100}
59
      skipDelayDuration={500}
60
      orientation="vertical"
61
    >
62
      {/* Menu items */}
63
    </NavigationMenu>
64
  );
65
}
66
```
67

68
### NavigationMenuList
69

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

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

81
interface NavigationMenuListProps 
82
  extends React.ComponentPropsWithoutRef<"ul"> {}
83
```
84

85
**Usage Examples:**
86

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

90
function NavWithList() {
91
  return (
92
    <NavigationMenu>
93
      <NavigationMenuList className="nav-list">
94
        <NavigationMenuItem>Item 1</NavigationMenuItem>
95
        <NavigationMenuItem>Item 2</NavigationMenuItem>
96
      </NavigationMenuList>
97
    </NavigationMenu>
98
  );
99
}
100
```
101

102
### NavigationMenuItem
103

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

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

115
interface NavigationMenuItemProps 
116
  extends React.ComponentPropsWithoutRef<"li"> {
117
  value?: string;
118
}
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
import { 
125
  NavigationMenu, 
126
  NavigationMenuList, 
127
  NavigationMenuItem,
128
  NavigationMenuTrigger,
129
  NavigationMenuContent 
130
} from "@radix-ui/react-navigation-menu";
131

132
function ItemExample() {
133
  return (
134
    <NavigationMenu>
135
      <NavigationMenuList>
136
        {/* Item with explicit value */}
137
        <NavigationMenuItem value="products">
138
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
139
          <NavigationMenuContent>
140
            Product content here
141
          </NavigationMenuContent>
142
        </NavigationMenuItem>
143
        
144
        {/* Item with auto-generated value */}
145
        <NavigationMenuItem>
146
          <NavigationMenuTrigger>Services</NavigationMenuTrigger>
147
          <NavigationMenuContent>
148
            Service content here
149
          </NavigationMenuContent>
150
        </NavigationMenuItem>
151
      </NavigationMenuList>
152
    </NavigationMenu>
153
  );
154
}
155
```
156

157
### NavigationMenuSub
158

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

161
```typescript { .api }
162
/**
163
 * Sub-navigation container for nested menu structures
164
 * @param value - Controlled value for the sub-menu
165
 * @param defaultValue - Default value for uncontrolled sub-menu
166
 * @param onValueChange - Callback when sub-menu value changes
167
 * @param orientation - Layout orientation for the sub-menu
168
 */
169
const NavigationMenuSub: React.ForwardRefExoticComponent<
170
  NavigationMenuSubProps & React.RefAttributes<HTMLDivElement>
171
>;
172

173
interface NavigationMenuSubProps 
174
  extends React.ComponentPropsWithoutRef<"div"> {
175
  value?: string;
176
  defaultValue?: string;
177
  onValueChange?: (value: string) => void;
178
  orientation?: "horizontal" | "vertical";
179
}
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { 
186
  NavigationMenu,
187
  NavigationMenuList,
188
  NavigationMenuItem,
189
  NavigationMenuTrigger,
190
  NavigationMenuContent,
191
  NavigationMenuSub
192
} from "@radix-ui/react-navigation-menu";
193

194
function NestedMenuExample() {
195
  return (
196
    <NavigationMenu>
197
      <NavigationMenuList>
198
        <NavigationMenuItem>
199
          <NavigationMenuTrigger>Products</NavigationMenuTrigger>
200
          <NavigationMenuContent>
201
            <NavigationMenuSub>
202
              <NavigationMenuList>
203
                <NavigationMenuItem>
204
                  <NavigationMenuTrigger>Web Tools</NavigationMenuTrigger>
205
                  <NavigationMenuContent>
206
                    Web tools content
207
                  </NavigationMenuContent>
208
                </NavigationMenuItem>
209
              </NavigationMenuList>
210
            </NavigationMenuSub>
211
          </NavigationMenuContent>
212
        </NavigationMenuItem>
213
      </NavigationMenuList>
214
    </NavigationMenu>
215
  );
216
}
217
```
218

219
## Data Attributes
220

221
Core components expose data attributes for styling:
222

223
### NavigationMenu Data Attributes
224

225
```css
226
[data-orientation="horizontal"] { /* Horizontal menu layout */ }
227
[data-orientation="vertical"] { /* Vertical menu layout */ }
228
```
229

230
### NavigationMenuList Data Attributes
231

232
```css
233
[data-orientation="horizontal"] { /* Horizontal list layout */ }
234
[data-orientation="vertical"] { /* Vertical list layout */ }
235
```
236

237
### NavigationMenuSub Data Attributes
238

239
```css
240
[data-orientation="horizontal"] { /* Horizontal sub-menu */ }
241
[data-orientation="vertical"] { /* Vertical sub-menu */ }
242
```
243

244
**Styling Examples:**
245

246
```css
247
.nav-menu[data-orientation="horizontal"] {
248
  display: flex;
249
  flex-direction: row;
250
}
251

252
.nav-menu[data-orientation="vertical"] {
253
  display: flex;
254
  flex-direction: column;
255
}
256

257
.nav-list[data-orientation="horizontal"] {
258
  display: flex;
259
  flex-direction: row;
260
  gap: 1rem;
261
}
262

263
.nav-list[data-orientation="vertical"] {
264
  display: flex;
265
  flex-direction: column;
266
  gap: 0.5rem;
267
}
268
```