0
# Core Components
1

2
Essential components for creating the basic menubar structure and managing overall state, keyboard navigation, and menu visibility.
3

4
## Capabilities
5

6
### Menubar (Root)
7

8
Root menubar container component that manages the overall menubar state and provides horizontal navigation between menu triggers.
9

10
```typescript { .api }
11
/**
12
 * Root menubar container with keyboard navigation and state management
13
 * @param props - Menubar configuration props
14
 * @returns JSX element representing the menubar
15
 */
16
function Menubar(props: MenubarProps): React.ReactElement;
17

18
interface MenubarProps extends React.ComponentPropsWithoutRef<'div'> {
19
  /** Controlled value for which menu is currently open */
20
  value?: string;
21
  /** Default value for which menu is open on initial render */
22
  defaultValue?: string;
23
  /** Callback fired when the open menu changes */
24
  onValueChange?: (value: string) => void;
25
  /** Whether navigation should loop from last to first item (default: true) */
26
  loop?: boolean;
27
  /** Text direction for the menubar (inherits from DirectionProvider if not specified) */
28
  dir?: 'ltr' | 'rtl';
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
'use client';
36
import * as Menubar from "@radix-ui/react-menubar";
37

38
// Basic menubar
39
function BasicMenubar() {
40
  return (
41
    <Menubar.Root>
42
      <Menubar.Menu>
43
        <Menubar.Trigger>File</Menubar.Trigger>
44
        {/* ... menu content */}
45
      </Menubar.Menu>
46
      <Menubar.Menu>
47
        <Menubar.Trigger>Edit</Menubar.Trigger>
48
        {/* ... menu content */}
49
      </Menubar.Menu>
50
    </Menubar.Root>
51
  );
52
}
53

54
// Controlled menubar
55
function ControlledMenubar() {
56
  const [activeMenu, setActiveMenu] = React.useState("");
57
  
58
  return (
59
    <Menubar.Root value={activeMenu} onValueChange={setActiveMenu}>
60
      <Menubar.Menu value="file">
61
        <Menubar.Trigger>File</Menubar.Trigger>
62
        {/* ... menu content */}
63
      </Menubar.Menu>
64
      <Menubar.Menu value="edit">
65
        <Menubar.Trigger>Edit</Menubar.Trigger>
66
        {/* ... menu content */}
67
      </Menubar.Menu>
68
    </Menubar.Root>
69
  );
70
}
71
```
72

73
### MenubarMenu (Menu)
74

75
Individual menu within the menubar that contains triggers and content. Each menu represents a distinct dropdown section.
76

77
```typescript { .api }
78
/**
79
 * Individual menu container within the menubar
80
 * @param props - Menu configuration props
81
 * @returns JSX element representing the menu
82
 */
83
function MenubarMenu(props: MenubarMenuProps): React.ReactElement;
84

85
interface MenubarMenuProps {
86
  /** Unique identifier for this menu (auto-generated if not provided) */
87
  value?: string;
88
  /** Child components (typically Trigger and Portal/Content) */
89
  children?: React.ReactNode;
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
// Basic menu with auto-generated value
97
<Menubar.Menu>
98
  <Menubar.Trigger>File</Menubar.Trigger>
99
  <Menubar.Portal>
100
    <Menubar.Content>
101
      <Menubar.Item>New</Menubar.Item>
102
    </Menubar.Content>
103
  </Menubar.Portal>
104
</Menubar.Menu>
105

106
// Menu with explicit value for controlled behavior
107
<Menubar.Menu value="file-menu">
108
  <Menubar.Trigger>File</Menubar.Trigger>
109
  {/* ... content */}
110
</Menubar.Menu>
111
```
112

113
### MenubarTrigger (Trigger)
114

115
Button that triggers the opening of a menu, with comprehensive keyboard and mouse interaction handling.
116

117
```typescript { .api }
118
/**
119
 * Button that triggers menu opening with keyboard and mouse support
120
 * @param props - Trigger button props
121
 * @returns JSX element representing the trigger button
122
 */
123
function MenubarTrigger(props: MenubarTriggerProps): React.ReactElement;
124

125
interface MenubarTriggerProps extends React.ComponentPropsWithoutRef<'button'> {
126
  /** All standard button props are supported */
127
}
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
// Basic trigger
134
<Menubar.Trigger>File</Menubar.Trigger>
135

136
// Trigger with custom styling and event handlers
137
<Menubar.Trigger 
138
  className="menu-trigger"
139
  onFocus={() => console.log("Trigger focused")}
140
>
141
  Edit
142
</Menubar.Trigger>
143

144
// Disabled trigger
145
<Menubar.Trigger disabled>
146
  Help
147
</Menubar.Trigger>
148
```
149

150
### MenubarPortal (Portal)
151

152
Portal component for rendering menu content outside the normal DOM tree, typically used for proper positioning and z-index management.
153

154
```typescript { .api }
155
/**
156
 * Portal for rendering menu content outside normal DOM hierarchy
157
 * @param props - Portal configuration props
158
 * @returns Portal-rendered content
159
 */
160
function MenubarPortal(props: MenubarPortalProps): React.ReactElement;
161

162
interface MenubarPortalProps {
163
  /** Target container for portal rendering (defaults to document.body) */
164
  container?: HTMLElement;
165
  /** Child components to render in the portal */
166
  children?: React.ReactNode;
167
}
168
```
169

170
**Usage Examples:**
171

172
```typescript
173
// Basic portal usage
174
<Menubar.Portal>
175
  <Menubar.Content>
176
    <Menubar.Item>Menu Item</Menubar.Item>
177
  </Menubar.Content>
178
</Menubar.Portal>
179

180
// Portal with custom container
181
<Menubar.Portal container={document.getElementById('modal-root')}>
182
  <Menubar.Content>
183
    <Menubar.Item>Menu Item</Menubar.Item>
184
  </Menubar.Content>
185
</Menubar.Portal>
186
```
187

188
### MenubarContent (Content)
189

190
Container for menu items with focus management, keyboard navigation, and positioning features.
191

192
```typescript { .api }
193
/**
194
 * Container for menu items with focus and keyboard management
195
 * @param props - Content container props
196
 * @returns JSX element representing the menu content
197
 */
198
function MenubarContent(props: MenubarContentProps): React.ReactElement;
199

200
interface MenubarContentProps extends React.ComponentPropsWithoutRef<'div'> {
201
  /** Alignment relative to trigger (default: 'start') */
202
  align?: 'start' | 'center' | 'end';
203
  /** Side preference for positioning */
204
  side?: 'top' | 'right' | 'bottom' | 'left';
205
  /** Distance from trigger in pixels */
206
  sideOffset?: number;
207
  /** Alignment offset in pixels */
208
  alignOffset?: number;
209
  /** Whether content should avoid collisions with the boundary */
210
  avoidCollisions?: boolean;
211
  /** Element or area to constrain positioning within */
212
  collisionBoundary?: Element | null | Array<Element | null>;
213
  /** Padding from collision boundary in pixels */
214
  collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
215
  /** Whether content should stick to trigger when boundary is reached */
216
  sticky?: 'partial' | 'always';
217
  /** Callback fired when content is closed via auto-focus */
218
  onCloseAutoFocus?: (event: Event) => void;
219
  /** Callback fired when focus moves outside the content */
220
  onFocusOutside?: (event: FocusOutsideEvent) => void;
221
  /** Callback fired when interaction occurs outside the content */
222
  onInteractOutside?: (event: InteractOutsideEvent) => void;
223
  /** Callback fired when escape key is pressed */
224
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
225
  /** Callback fired when pointer moves down outside the content */
226
  onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
// Basic content
234
<Menubar.Content>
235
  <Menubar.Item>New File</Menubar.Item>
236
  <Menubar.Item>Open</Menubar.Item>
237
  <Menubar.Separator />
238
  <Menubar.Item>Exit</Menubar.Item>
239
</Menubar.Content>
240

241
// Content with custom positioning
242
<Menubar.Content 
243
  align="center" 
244
  side="bottom" 
245
  sideOffset={5}
246
  onCloseAutoFocus={(event) => {
247
    // Custom focus handling
248
    event.preventDefault();
249
  }}
250
>
251
  <Menubar.Item>Centered Menu Item</Menubar.Item>
252
</Menubar.Content>
253
```
254

255
**Key Implementation Details:**
256

257
- **Data Attributes**: Content automatically receives `data-radix-menubar-content=""` attribute
258
- **CSS Custom Properties**: The following variables are available for styling:
259
  - `--radix-menubar-content-transform-origin`: Transform origin for animations
260
  - `--radix-menubar-content-available-width`: Available width for content
261
  - `--radix-menubar-content-available-height`: Available height for content  
262
  - `--radix-menubar-trigger-width`: Width of the triggering element
263
  - `--radix-menubar-trigger-height`: Height of the triggering element
264
- **Focus Behavior**: Content manages focus automatically with keyboard navigation support
265
- **Keyboard Navigation**: Arrow keys navigate between menu triggers when content is open
266

267
## Type Definitions
268

269
```typescript { .api }
270
// Element reference types
271
type MenubarElement = React.ComponentRef<'div'>;
272
type MenubarTriggerElement = React.ComponentRef<'button'>;
273
type MenubarContentElement = HTMLDivElement;
274

275
// Event types
276
interface FocusOutsideEvent {
277
  target: HTMLElement;
278
  preventDefault(): void;
279
}
280

281
interface InteractOutsideEvent {
282
  target: HTMLElement;
283
  preventDefault(): void;
284
}
285

286
interface PointerDownOutsideEvent {
287
  target: HTMLElement;
288
  preventDefault(): void;
289
}
290

291
// Direction type
292
type Direction = 'ltr' | 'rtl';
293

294
// Portal container type
295
type PortalContainer = HTMLElement | null;
296
```