0
# Radix UI React Dropdown Menu
1

2
A React dropdown menu component library that provides accessible dropdown menu functionality with keyboard navigation, focus management, and customizable styling. Part of the Radix UI Primitives library, it offers a complete set of components for building dropdown menus with full accessibility compliance and keyboard navigation support.
3

4
## Package Information
5

6
- **Package Name**: @radix-ui/react-dropdown-menu
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @radix-ui/react-dropdown-menu`
10

11
## Core Imports
12

13
```typescript
14
import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
15
```
16

17
Named imports:
18

19
```typescript
20
import {
21
  DropdownMenu,
22
  DropdownMenuTrigger,
23
  DropdownMenuContent,
24
  DropdownMenuItem,
25
  DropdownMenuCheckboxItem,
26
  DropdownMenuRadioGroup,
27
  DropdownMenuRadioItem,
28
  DropdownMenuSeparator,
29
} from "@radix-ui/react-dropdown-menu";
30
```
31

32
Short alias imports:
33

34
```typescript
35
import {
36
  Root,
37
  Trigger,
38
  Content,
39
  Item,
40
  CheckboxItem,
41
  RadioGroup,
42
  RadioItem,
43
  Separator,
44
} from "@radix-ui/react-dropdown-menu";
45
```
46

47
## Basic Usage
48

49
```typescript
50
import React from "react";
51
import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
52

53
function App() {
54
  return (
55
    <DropdownMenu.Root>
56
      <DropdownMenu.Trigger asChild>
57
        <button>Options</button>
58
      </DropdownMenu.Trigger>
59
      
60
      <DropdownMenu.Portal>
61
        <DropdownMenu.Content>
62
          <DropdownMenu.Item>New Tab</DropdownMenu.Item>
63
          <DropdownMenu.Item>New Window</DropdownMenu.Item>
64
          <DropdownMenu.Separator />
65
          <DropdownMenu.Item>Settings</DropdownMenu.Item>
66
        </DropdownMenu.Content>
67
      </DropdownMenu.Portal>
68
    </DropdownMenu.Root>
69
  );
70
}
71
```
72

73
## Architecture
74

75
Radix UI React Dropdown Menu is built on several architectural principles:
76

77
- **Composition-based**: Components work together through React composition patterns
78
- **Menu Primitive Foundation**: Built on top of @radix-ui/react-menu for core functionality
79
- **Context-driven State**: Uses React Context for component communication and state management
80
- **Accessibility First**: Full ARIA compliance with proper roles, attributes, and keyboard navigation
81
- **Portal Rendering**: Uses portal-based rendering for proper overlay positioning and z-index management
82
- **Controlled/Uncontrolled**: Supports both controlled and uncontrolled state management patterns
83

84
## Capabilities
85

86
### Core Components
87

88
Essential components for building dropdown menus including the root container, trigger button, and content area.
89

90
```typescript { .api }
91
// Root container managing dropdown state
92
interface DropdownMenuProps {
93
  children?: React.ReactNode;
94
  dir?: 'ltr' | 'rtl';
95
  open?: boolean;  
96
  defaultOpen?: boolean;
97
  onOpenChange?(open: boolean): void;
98
  modal?: boolean;
99
}
100

101
// Trigger button component
102
interface DropdownMenuTriggerProps extends React.ComponentPropsWithoutRef<'button'> {}
103

104
// Content container for menu items
105
interface DropdownMenuContentProps {
106
  align?: 'start' | 'center' | 'end';
107
  side?: 'top' | 'right' | 'bottom' | 'left';
108
  sideOffset?: number;
109
  alignOffset?: number;
110
  avoidCollisions?: boolean;
111
  collisionBoundary?: Element | null | Array<Element | null>;
112
  collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
113
  sticky?: 'partial' | 'always';
114
  hideWhenDetached?: boolean;
115
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
116
  onPointerDownOutside?: (event: CustomEvent<{ originalEvent: PointerEvent }>) => void;
117
  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
118
  onInteractOutside?: (event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>) => void;
119
  children?: React.ReactNode;
120
}
121
```
122

123
[Core Components](./core-components.md)
124

125
### Menu Items
126

127
Individual menu items including basic items, checkbox items, radio items, and their indicators.
128

129
```typescript { .api }
130
// Basic menu item
131
interface DropdownMenuItemProps {
132
  disabled?: boolean;
133
  onSelect?: (event: Event) => void;
134
  textValue?: string;
135
  asChild?: boolean;
136
  children?: React.ReactNode;
137
}
138

139
// Checkbox menu item
140
interface DropdownMenuCheckboxItemProps {
141
  checked?: boolean | 'indeterminate';
142
  onCheckedChange?: (checked: boolean) => void;
143
  disabled?: boolean;
144
  onSelect?: (event: Event) => void;
145
  textValue?: string;
146
  children?: React.ReactNode;
147
}
148

149
// Radio group container
150
interface DropdownMenuRadioGroupProps {
151
  value?: string;
152
  onValueChange?: (value: string) => void;
153
  children?: React.ReactNode;
154
}
155

156
// Radio menu item
157
interface DropdownMenuRadioItemProps {
158
  value: string;
159
  disabled?: boolean;
160
  onSelect?: (event: Event) => void;
161
  textValue?: string;
162
  children?: React.ReactNode;
163
}
164

165
// Item indicator for checkbox/radio items
166
interface DropdownMenuItemIndicatorProps {
167
  forceMount?: boolean;
168
  children?: React.ReactNode;
169
}
170
```
171

172
[Menu Items](./menu-items.md)
173

174
### Layout Components
175

176
Components for organizing and structuring menu layout including groups, labels, separators, and arrows.
177

178
```typescript { .api }
179
// Group related menu items
180
interface DropdownMenuGroupProps {
181
  children?: React.ReactNode;
182
}
183

184
// Label for menu sections
185
interface DropdownMenuLabelProps {
186
  asChild?: boolean;
187
  children?: React.ReactNode;
188
}
189

190
// Visual separator
191
interface DropdownMenuSeparatorProps {
192
  children?: React.ReactNode;
193
}
194

195
// Arrow pointing to trigger
196
interface DropdownMenuArrowProps {
197
  width?: number;
198
  height?: number;
199
  asChild?: boolean;
200
}
201
```
202

203
[Layout Components](./layout-components.md)
204

205
### Submenus
206

207
Components for creating nested dropdown menus with submenu triggers and content areas.
208

209
```typescript { .api }
210
// Submenu container
211
interface DropdownMenuSubProps {
212
  children?: React.ReactNode;
213
  open?: boolean;
214
  defaultOpen?: boolean;
215
  onOpenChange?(open: boolean): void;
216
}
217

218
// Submenu trigger
219
interface DropdownMenuSubTriggerProps {
220
  disabled?: boolean;
221
  textValue?: string;
222
  asChild?: boolean;
223
  children?: React.ReactNode;
224
}
225

226
// Submenu content
227
interface DropdownMenuSubContentProps {
228
  loop?: boolean;
229
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
230
  onKeyDown?: (event: KeyboardEvent) => void;
231
  forceMount?: boolean;
232
  container?: HTMLElement;
233
  children?: React.ReactNode;
234
}
235
```
236

237
[Submenus](./submenus.md)
238

239
### Portal and Context
240

241
Portal component for rendering menu content and context utilities for advanced customization.
242

243
```typescript { .api }
244
// Portal for rendering content
245
interface DropdownMenuPortalProps {
246
  forceMount?: boolean;
247
  container?: HTMLElement;
248
  children?: React.ReactNode;
249
}
250

251
// Context scope creation utility
252
function createDropdownMenuScope(): any;
253
```
254

255
[Portal and Context](./portal-context.md)
256

257
## Types
258

259
```typescript { .api }
260
// Direction for menu layout
261
type Direction = 'ltr' | 'rtl';
262

263
// Context scope type
264
type Scope = any;
265

266
// Scoped props pattern for context
267
type ScopedProps<P> = P & { __scopeDropdownMenu?: Scope };
268
```