0
# Portal and Context
1

2
Portal component for rendering menu content and context utilities for advanced customization. These components provide lower-level control over rendering behavior and component scope.
3

4
## Capabilities
5

6
### DropdownMenuPortal (Portal)
7

8
Portal component that renders dropdown content outside the normal DOM hierarchy for proper layering and positioning.
9

10
```typescript { .api }
11
/**
12
 * Portal for rendering dropdown content outside normal DOM flow
13
 * @param forceMount - Force mounting regardless of open state
14
 * @param container - Container element to portal into (defaults to document.body)
15
 * @param children - Content to be portaled (typically DropdownMenuContent)
16
 */
17
interface DropdownMenuPortalProps {
18
  forceMount?: boolean;
19
  container?: HTMLElement;
20
  children?: React.ReactNode;
21
}
22

23
const DropdownMenuPortal: React.FC<DropdownMenuPortalProps>;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
// Basic portal usage
30
<DropdownMenu.Root>
31
  <DropdownMenu.Trigger>Menu</DropdownMenu.Trigger>
32
  <DropdownMenu.Portal>
33
    <DropdownMenu.Content>
34
      <DropdownMenu.Item>Item 1</DropdownMenu.Item>
35
    </DropdownMenu.Content>
36
  </DropdownMenu.Portal>
37
</DropdownMenu.Root>
38

39
// Portal to specific container
40
const portalContainer = document.getElementById('modal-root');
41
<DropdownMenu.Portal container={portalContainer}>
42
  <DropdownMenu.Content>
43
    <DropdownMenu.Item>Portaled Item</DropdownMenu.Item>
44
  </DropdownMenu.Content>
45
</DropdownMenu.Portal>
46

47
// Force-mounted portal (always rendered)
48
<DropdownMenu.Portal forceMount>
49
  <DropdownMenu.Content>
50
    <DropdownMenu.Item>Always Present</DropdownMenu.Item>
51
  </DropdownMenu.Content>
52
</DropdownMenu.Portal>
53

54
// Without portal (content renders in place)
55
<DropdownMenu.Root>
56
  <DropdownMenu.Trigger>Menu</DropdownMenu.Trigger>
57
  <DropdownMenu.Content>
58
    <DropdownMenu.Item>Inline Item</DropdownMenu.Item>
59
  </DropdownMenu.Content>
60
</DropdownMenu.Root>
61
```
62

63
### createDropdownMenuScope
64

65
Context scope creation utility for advanced component composition and avoiding context conflicts.
66

67
```typescript { .api }
68
/**
69
 * Creates a scoped context for dropdown menu components
70
 * Used for advanced composition patterns and avoiding context conflicts
71
 * @returns Scoped context creation functions
72
 */
73
function createDropdownMenuScope(): any;
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
// Advanced usage with custom scope
80
const useCustomScope = createDropdownMenuScope();
81

82
function CustomDropdownMenu() {
83
  const customScope = useCustomScope();
84
  
85
  return (
86
    <DropdownMenu.Root {...customScope}>
87
      <DropdownMenu.Trigger {...customScope}>
88
        Custom Scoped Menu
89
      </DropdownMenu.Trigger>
90
      <DropdownMenu.Portal {...customScope}>
91
        <DropdownMenu.Content {...customScope}>
92
          <DropdownMenu.Item {...customScope}>
93
            Scoped Item
94
          </DropdownMenu.Item>
95
        </DropdownMenu.Content>
96
      </DropdownMenu.Portal>
97
    </DropdownMenu.Root>
98
  );
99
}
100
```
101

102
## Advanced Portal Patterns
103

104
### Multiple Portals
105

106
```typescript
107
function MultiPortalExample() {
108
  return (
109
    <div>
110
      {/* First dropdown with default portal */}
111
      <DropdownMenu.Root>
112
        <DropdownMenu.Trigger>Menu 1</DropdownMenu.Trigger>
113
        <DropdownMenu.Portal>
114
          <DropdownMenu.Content>
115
            <DropdownMenu.Item>Item 1</DropdownMenu.Item>
116
          </DropdownMenu.Content>
117
        </DropdownMenu.Portal>
118
      </DropdownMenu.Root>
119
      
120
      {/* Second dropdown with custom portal container */}
121
      <DropdownMenu.Root>
122
        <DropdownMenu.Trigger>Menu 2</DropdownMenu.Trigger>
123
        <DropdownMenu.Portal container={document.getElementById('custom-layer')}>
124
          <DropdownMenu.Content>
125
            <DropdownMenu.Item>Item 2</DropdownMenu.Item>
126
          </DropdownMenu.Content>
127
        </DropdownMenu.Portal>
128
      </DropdownMenu.Root>
129
    </div>
130
  );
131
}
132
```
133

134
### Conditional Portal
135

136
```typescript
137
function ConditionalPortalExample() {
138
  const [usePortal, setUsePortal] = React.useState(true);
139
  
140
  const content = (
141
    <DropdownMenu.Content>
142
      <DropdownMenu.Item>Item</DropdownMenu.Item>
143
    </DropdownMenu.Content>
144
  );
145
  
146
  return (
147
    <DropdownMenu.Root>
148
      <DropdownMenu.Trigger>Menu</DropdownMenu.Trigger>
149
      {usePortal ? (
150
        <DropdownMenu.Portal>{content}</DropdownMenu.Portal>
151
      ) : (
152
        content
153
      )}
154
    </DropdownMenu.Root>
155
  );
156
}
157
```
158

159
## Context Scoping Benefits
160

161
- **Isolation**: Prevents context bleeding between multiple dropdown instances
162
- **Composition**: Enables building custom dropdown variations
163
- **Testing**: Allows isolated testing of dropdown components
164
- **Performance**: Reduces unnecessary re-renders in complex component trees
165

166
## When to Use Portal
167

168
**Use Portal when:**
169
- Content needs to appear above other page elements (z-index issues)
170
- Working with modals, overlays, or fixed positioning
171
- Need to escape parent container's overflow: hidden
172
- Building complex layered interfaces
173

174
**Skip Portal when:**
175
- Simple in-page menus without layering concerns
176
- Content should scroll with parent container
177
- Working within already-portaled contexts
178
- Performance optimization for simple cases
179

180
## Component Aliases
181

182
```typescript { .api }
183
// Short aliases for composition patterns
184
const Portal = DropdownMenuPortal;
185
```
186

187
These portal and context utilities provide advanced control over dropdown rendering behavior and enable sophisticated composition patterns while maintaining proper accessibility and functionality.