# Radix UI React Dropdown Menu

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.

## Package Information

- **Package Name**: @radix-ui/react-dropdown-menu
- **Package Type**: npm
- **Language**: TypeScript
- **Installation**: `npm install @radix-ui/react-dropdown-menu`

## Core Imports

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

Named imports:

```typescript
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
} from "@radix-ui/react-dropdown-menu";
```

Short alias imports:

```typescript
import {
  Root,
  Trigger,
  Content,
  Item,
  CheckboxItem,
  RadioGroup,
  RadioItem,
  Separator,
} from "@radix-ui/react-dropdown-menu";
```

## Basic Usage

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

function App() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <button>Options</button>
      </DropdownMenu.Trigger>
      
      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.Item>New Tab</DropdownMenu.Item>
          <DropdownMenu.Item>New Window</DropdownMenu.Item>
          <DropdownMenu.Separator />
          <DropdownMenu.Item>Settings</DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}
```

## Architecture

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

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

## Capabilities

### Core Components

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

```typescript { .api }
// Root container managing dropdown state
interface DropdownMenuProps {
  children?: React.ReactNode;
  dir?: 'ltr' | 'rtl';
  open?: boolean;  
  defaultOpen?: boolean;
  onOpenChange?(open: boolean): void;
  modal?: boolean;
}

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

// Content container for menu items
interface DropdownMenuContentProps {
  align?: 'start' | 'center' | 'end';
  side?: 'top' | 'right' | 'bottom' | 'left';
  sideOffset?: number;
  alignOffset?: number;
  avoidCollisions?: boolean;
  collisionBoundary?: Element | null | Array<Element | null>;
  collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
  sticky?: 'partial' | 'always';
  hideWhenDetached?: boolean;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onPointerDownOutside?: (event: CustomEvent<{ originalEvent: PointerEvent }>) => void;
  onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
  onInteractOutside?: (event: CustomEvent<{ originalEvent: PointerEvent | FocusEvent }>) => void;
  children?: React.ReactNode;
}
```

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

### Menu Items

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

```typescript { .api }
// Basic menu item
interface DropdownMenuItemProps {
  disabled?: boolean;
  onSelect?: (event: Event) => void;
  textValue?: string;
  asChild?: boolean;
  children?: React.ReactNode;
}

// Checkbox menu item
interface DropdownMenuCheckboxItemProps {
  checked?: boolean | 'indeterminate';
  onCheckedChange?: (checked: boolean) => void;
  disabled?: boolean;
  onSelect?: (event: Event) => void;
  textValue?: string;
  children?: React.ReactNode;
}

// Radio group container
interface DropdownMenuRadioGroupProps {
  value?: string;
  onValueChange?: (value: string) => void;
  children?: React.ReactNode;
}

// Radio menu item
interface DropdownMenuRadioItemProps {
  value: string;
  disabled?: boolean;
  onSelect?: (event: Event) => void;
  textValue?: string;
  children?: React.ReactNode;
}

// Item indicator for checkbox/radio items
interface DropdownMenuItemIndicatorProps {
  forceMount?: boolean;
  children?: React.ReactNode;
}
```

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

### Layout Components

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

```typescript { .api }
// Group related menu items
interface DropdownMenuGroupProps {
  children?: React.ReactNode;
}

// Label for menu sections
interface DropdownMenuLabelProps {
  asChild?: boolean;
  children?: React.ReactNode;
}

// Visual separator
interface DropdownMenuSeparatorProps {
  children?: React.ReactNode;
}

// Arrow pointing to trigger
interface DropdownMenuArrowProps {
  width?: number;
  height?: number;
  asChild?: boolean;
}
```

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

### Submenus

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

```typescript { .api }
// Submenu container
interface DropdownMenuSubProps {
  children?: React.ReactNode;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?(open: boolean): void;
}

// Submenu trigger
interface DropdownMenuSubTriggerProps {
  disabled?: boolean;
  textValue?: string;
  asChild?: boolean;
  children?: React.ReactNode;
}

// Submenu content
interface DropdownMenuSubContentProps {
  loop?: boolean;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onKeyDown?: (event: KeyboardEvent) => void;
  forceMount?: boolean;
  container?: HTMLElement;
  children?: React.ReactNode;
}
```

[Submenus](./submenus.md)

### Portal and Context

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

```typescript { .api }
// Portal for rendering content
interface DropdownMenuPortalProps {
  forceMount?: boolean;
  container?: HTMLElement;
  children?: React.ReactNode;
}

// Context scope creation utility
function createDropdownMenuScope(): any;
```

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

## Types

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

// Context scope type
type Scope = any;

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