0
# Utility Functions
1
2
Context scope creation utilities for managing navigation menu instances.
3
4
## Capabilities
5
6
### createNavigationMenuScope
7
8
Creates isolated context scopes for navigation menu components to prevent conflicts between multiple navigation menu instances.
9
10
```typescript { .api }
11
/**
12
* Creates a scoped context factory for navigation menu components
13
* Used internally by Radix to prevent context conflicts between multiple
14
* navigation menu instances. Returns scope creation utilities.
15
*/
16
function createNavigationMenuScope(): CreateScope;
17
```
18
19
**Key Features:**
20
- Enables multiple independent navigation menus on the same page
21
- Provides context isolation between different navigation menu instances
22
- Used internally by the navigation menu system
23
- Works with collection and focus group scopes
24
25
**Note:** This is primarily an internal utility function used by the Radix UI system for context management. Most applications do not need to use this function directly, as each NavigationMenu component automatically creates its own isolated scope.
26
27
**Usage Examples:**
28
29
```typescript
30
import { createNavigationMenuScope } from "@radix-ui/react-navigation-menu";
31
32
// Basic usage (rarely needed in applications)
33
const useCustomNavigationMenuScope = createNavigationMenuScope();
34
35
// The scope is typically used internally by NavigationMenu components
36
// Most users don't need to interact with this directly
37
38
// Example of internal usage pattern (for reference)
39
function CustomNavigationWrapper() {
40
// In most cases, you would just use NavigationMenu directly
41
// which handles scoping automatically
42
return (
43
<NavigationMenu>
44
{/* Components automatically use proper scoping */}
45
</NavigationMenu>
46
);
47
}
48
```
49
50
## Context Architecture
51
52
The navigation menu uses a sophisticated context system:
53
54
### Internal Context Structure
55
56
```typescript
57
// Internal context types (for reference)
58
type NavigationMenuContextValue = {
59
isRootMenu: boolean;
60
value: string;
61
previousValue: string;
62
baseId: string;
63
dir: "ltr" | "rtl";
64
orientation: "horizontal" | "vertical";
65
rootNavigationMenu: HTMLElement | null;
66
indicatorTrack: HTMLDivElement | null;
67
onIndicatorTrackChange(indicatorTrack: HTMLDivElement | null): void;
68
viewport: HTMLDivElement | null;
69
onViewportChange(viewport: HTMLDivElement | null): void;
70
onViewportContentChange(contentValue: string, contentData: ContentData): void;
71
onViewportContentRemove(contentValue: string): void;
72
onTriggerEnter(itemValue: string): void;
73
onTriggerLeave(): void;
74
onContentEnter(): void;
75
onContentLeave(): void;
76
onItemSelect(itemValue: string): void;
77
onItemDismiss(): void;
78
};
79
```
80
81
### Multiple Navigation Menus
82
83
When you need multiple navigation menus, each NavigationMenu component automatically creates its own scope:
84
85
```typescript
86
import {
87
NavigationMenu,
88
NavigationMenuList,
89
NavigationMenuItem,
90
NavigationMenuTrigger,
91
NavigationMenuContent
92
} from "@radix-ui/react-navigation-menu";
93
94
// Multiple independent navigation menus
95
function MultipleNavigationExample() {
96
return (
97
<div>
98
{/* First navigation menu - automatically scoped */}
99
<NavigationMenu>
100
<NavigationMenuList>
101
<NavigationMenuItem>
102
<NavigationMenuTrigger>Products</NavigationMenuTrigger>
103
<NavigationMenuContent>Products content</NavigationMenuContent>
104
</NavigationMenuItem>
105
</NavigationMenuList>
106
</NavigationMenu>
107
108
{/* Second navigation menu - automatically scoped */}
109
<NavigationMenu>
110
<NavigationMenuList>
111
<NavigationMenuItem>
112
<NavigationMenuTrigger>Services</NavigationMenuTrigger>
113
<NavigationMenuContent>Services content</NavigationMenuContent>
114
</NavigationMenuItem>
115
</NavigationMenuList>
116
</NavigationMenu>
117
</div>
118
);
119
}
120
```
121
122
### Nested Navigation Structures
123
124
For nested navigation, use NavigationMenuSub within content:
125
126
```typescript
127
function NestedNavigationExample() {
128
return (
129
<NavigationMenu>
130
<NavigationMenuList>
131
<NavigationMenuItem>
132
<NavigationMenuTrigger>Main Category</NavigationMenuTrigger>
133
<NavigationMenuContent>
134
{/* Use NavigationMenuSub for nested structure */}
135
<NavigationMenuSub>
136
<NavigationMenuList>
137
<NavigationMenuItem>
138
<NavigationMenuTrigger>Subcategory</NavigationMenuTrigger>
139
<NavigationMenuContent>Sub-content</NavigationMenuContent>
140
</NavigationMenuItem>
141
</NavigationMenuList>
142
</NavigationMenuSub>
143
</NavigationMenuContent>
144
</NavigationMenuItem>
145
</NavigationMenuList>
146
</NavigationMenu>
147
);
148
}
149
```
150
151
## Best Practices
152
153
### Scope Management
154
- **Automatic Scoping**: NavigationMenu components handle scoping automatically
155
- **No Manual Scoping**: Most applications don't need to manage scopes manually
156
- **Multiple Menus**: Each NavigationMenu creates its own isolated context
157
158
### When Manual Scoping Might Be Needed
159
1. **Custom Component Wrappers**: When building complex wrapper components
160
2. **Advanced Integration**: When integrating with other context systems
161
3. **Testing**: When mocking navigation menu contexts for tests
162
163
### Recommended Pattern
164
```typescript
165
// Preferred: Let NavigationMenu handle scoping automatically
166
function RecommendedNavigation() {
167
return (
168
<NavigationMenu>
169
<NavigationMenuList>
170
<NavigationMenuItem>
171
<NavigationMenuTrigger>Item</NavigationMenuTrigger>
172
<NavigationMenuContent>Content</NavigationMenuContent>
173
</NavigationMenuItem>
174
</NavigationMenuList>
175
</NavigationMenu>
176
);
177
}
178
179
// Avoid: Manual scope management (unless specifically needed)
180
// Most applications should not need to use createNavigationMenuScope directly
181
```