0
# Core Components
1

2
Essential components for building dropdown menus including the root container, trigger button, and content area. These components form the foundation of every dropdown menu implementation.
3

4
## Capabilities
5

6
### DropdownMenu (Root)
7

8
Root container component that manages dropdown menu state and provides context to child components.
9

10
```typescript { .api }
11
/**
12
 * Root container managing dropdown menu state
13
 * @param children - Child components (typically Trigger and Portal)
14
 * @param dir - Reading direction for layout
15
 * @param open - Controlled open state
16
 * @param defaultOpen - Default open state (uncontrolled)
17
 * @param onOpenChange - Callback when open state changes
18
 * @param modal - Whether menu should be modal (default: true)
19
 */
20
interface DropdownMenuProps {
21
  children?: React.ReactNode;
22
  dir?: 'ltr' | 'rtl';
23
  open?: boolean;
24
  defaultOpen?: boolean;
25
  onOpenChange?(open: boolean): void;
26
  modal?: boolean;
27
}
28

29
const DropdownMenu: React.FC<DropdownMenuProps>;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
36

37
// Uncontrolled dropdown
38
<DropdownMenu.Root defaultOpen={false}>
39
  {/* trigger and content */}
40
</DropdownMenu.Root>
41

42
// Controlled dropdown
43
const [open, setOpen] = React.useState(false);
44
<DropdownMenu.Root open={open} onOpenChange={setOpen}>
45
  {/* trigger and content */}
46
</DropdownMenu.Root>
47

48
// Non-modal dropdown (allows interaction outside)
49
<DropdownMenu.Root modal={false}>
50
  {/* trigger and content */}
51
</DropdownMenu.Root>
52
```
53

54
### DropdownMenuTrigger (Trigger)
55

56
Button component that triggers the dropdown menu when clicked or activated with keyboard.
57

58
```typescript { .api }
59
/**
60
 * Trigger button component that opens/closes the dropdown
61
 * Extends all HTML button attributes and props
62
 * @param disabled - Whether the trigger is disabled
63
 * @param asChild - Compose with child element instead of rendering button
64
 */
65
interface DropdownMenuTriggerProps extends React.ComponentPropsWithoutRef<'button'> {
66
  disabled?: boolean;
67
  asChild?: boolean;
68
}
69

70
const DropdownMenuTrigger: React.ForwardRefExoticComponent<DropdownMenuTriggerProps>;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
// Basic trigger
77
<DropdownMenu.Trigger>
78
  Menu
79
</DropdownMenu.Trigger>
80

81
// Custom trigger using asChild
82
<DropdownMenu.Trigger asChild>
83
  <button className="custom-button">
84
    <MenuIcon />
85
    Options
86
  </button>
87
</DropdownMenu.Trigger>
88

89
// Disabled trigger
90
<DropdownMenu.Trigger disabled>
91
  Unavailable
92
</DropdownMenu.Trigger>
93
```
94

95
### DropdownMenuContent (Content)
96

97
Main content container that holds all menu items and appears as an overlay when the dropdown is open.
98

99
```typescript { .api }
100
/**
101
 * Content container for menu items, rendered as an overlay
102
 * @param align - Alignment relative to trigger ('start' | 'center' | 'end')
103
 * @param side - Preferred side to render on ('top' | 'right' | 'bottom' | 'left')
104
 * @param sideOffset - Distance from trigger in pixels
105
 * @param alignOffset - Offset from alignment position
106
 * @param avoidCollisions - Whether to avoid viewport collisions
107
 * @param collisionBoundary - Element(s) to avoid collisions with
108
 * @param collisionPadding - Padding from collision boundary
109
 * @param sticky - Sticky behavior ('partial' | 'always')
110
 * @param hideWhenDetached - Hide when trigger becomes fully obscured
111
 * @param onEscapeKeyDown - Callback when Escape key is pressed
112
 * @param onPointerDownOutside - Callback when pointer down occurs outside
113
 * @param onFocusOutside - Callback when focus moves outside
114
 * @param onInteractOutside - Callback when interaction occurs outside
115
 */
116
interface DropdownMenuContentProps {
117
  align?: 'start' | 'center' | 'end';
118
  side?: 'top' | 'right' | 'bottom' | 'left';
119
  sideOffset?: number;
120
  alignOffset?: number;
121
  avoidCollisions?: boolean;
122
  collisionBoundary?: Element | null | Array<Element | null>;
123
  collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
124
  sticky?: 'partial' | 'always';
125
  hideWhenDetached?: boolean;
126
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
127
  onPointerDownOutside?: (event: CustomEvent<{ originalEvent: PointerEvent }>) => void;
128
  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
129
  onInteractOutside?: (event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>) => void;
130
  children?: React.ReactNode;
131
}
132

133
const DropdownMenuContent: React.ForwardRefExoticComponent<DropdownMenuContentProps>;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
// Basic content
140
<DropdownMenu.Content>
141
  <DropdownMenu.Item>Option 1</DropdownMenu.Item>
142
  <DropdownMenu.Item>Option 2</DropdownMenu.Item>
143
</DropdownMenu.Content>
144

145
// Positioned content
146
<DropdownMenu.Content 
147
  side="right" 
148
  align="start" 
149
  sideOffset={5}
150
>
151
  <DropdownMenu.Item>Right-aligned menu</DropdownMenu.Item>
152
</DropdownMenu.Content>
153

154
// Content with collision avoidance
155
<DropdownMenu.Content
156
  avoidCollisions={true}
157
  collisionPadding={10}
158
  sticky="partial"
159
>
160
  <DropdownMenu.Item>Auto-positioned</DropdownMenu.Item>
161
</DropdownMenu.Content>
162

163
// Content with custom event handlers
164
<DropdownMenu.Content
165
  onEscapeKeyDown={(e) => console.log('Escape pressed')}
166
  onInteractOutside={(e) => console.log('Clicked outside')}
167
>
168
  <DropdownMenu.Item>Menu item</DropdownMenu.Item>
169
</DropdownMenu.Content>
170
```
171

172
## Component Aliases
173

174
```typescript { .api }
175
// Short aliases for composition patterns
176
const Root = DropdownMenu;
177
const Trigger = DropdownMenuTrigger;
178
const Content = DropdownMenuContent;
179
```
180

181
These components provide the foundational structure for dropdown menus and must be used together to create a functional dropdown interface.