# DropdownMenu

## Overview

A triggered contextual menu that appears anchored below (or beside) a trigger element. Used for row actions in tables, secondary navigation options, and grouped control menus. Built on Radix UI with full keyboard navigation.

---

## When to Use

- Row-level action menus in tables (`MoreHorizontal` icon trigger)
- User profile menus in the Header
- Grouped options that don't warrant a full dialog

## When NOT to Use

- Select-one-from-list inputs — use `<Select>` instead.
- Right-click menus — use `<ContextMenu>` instead.
- Top-level application navigation — use `<NavigationMenu>` or `<Sidebar>`.

---

## Anatomy

```
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button />
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuLabel />
    <DropdownMenuSeparator />
    <DropdownMenuItem />
    <DropdownMenuSub>
      <DropdownMenuSubTrigger />
      <DropdownMenuSubContent>
        <DropdownMenuItem />
      </DropdownMenuSubContent>
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>
```

---

## Props

### DropdownMenu

| Prop           | Type                      | Description           |
| -------------- | ------------------------- | --------------------- |
| `open`         | `boolean`                 | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | State handler         |

### DropdownMenuContent

| Prop         | Type                           | Default   | Description                     |
| ------------ | ------------------------------ | --------- | ------------------------------- |
| `align`      | `'start' \| 'center' \| 'end'` | `'start'` | Horizontal alignment to trigger |
| `sideOffset` | `number`                       | `4`       | Vertical offset from trigger    |
| `className`  | `string`                       | —         | Width and style overrides       |

### DropdownMenuItem

| Prop        | Type         | Description                                                  |
| ----------- | ------------ | ------------------------------------------------------------ |
| `onClick`   | `() => void` | Action handler                                               |
| `className` | `string`     | Additional classes (use `text-destructive` for danger items) |
| `disabled`  | `boolean`    | Disables the item                                            |

---

## Examples

### Table Row Actions

```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
  Button,
} from 'xertica-ui/ui';
import { MoreHorizontal } from 'lucide-react';

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="ghost" size="icon" className="size-8">
      <MoreHorizontal className="size-4" />
    </Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuLabel>Actions</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem onClick={() => handleEdit(record)}>Edit</DropdownMenuItem>
    <DropdownMenuItem onClick={() => handleDuplicate(record)}>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem
      className="text-destructive focus:text-destructive"
      onClick={() => handleDelete(record)}
    >
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>;
```

---

## AI Rules

- **Always** use `<DropdownMenuTrigger asChild>` — never without `asChild` when the trigger is a `<Button>`.
- **Destructive menu items** (Delete, Revoke, Disable) must use `className="text-destructive focus:text-destructive"`.
- When a destructive item is clicked, it should open an `<AlertDialog>` — never execute the action directly.
- Use `<DropdownMenuSeparator>` to visually group items. Destructive items are always separated from safe items.
- `align="end"` is standard for table row menus (aligns to the right side of the trigger button).

---

## Related Components

- [`ContextMenu`](./context-menu.md) — Right-click variant
- [`AlertDialog`](./alert-dialog.md) — For destructive confirmations from menu items
- [`Button`](./button.md) — The trigger element