# ContextMenu

## Overview

A menu that appears when the user right-clicks (or long-presses on mobile) a trigger area. Provides a familiar OS-native contextual menu pattern for power-user interactions. Built on Radix UI.

---

## When to Use

- Right-click context menus on list items, table rows, or canvas elements
- Power-user shortcuts for common operations
- When users need quick access to multiple actions on an item without cluttering the UI with buttons

## When NOT to Use

- Primary discoverable actions — use `<Button>` or `<DropdownMenu>` instead (right-click menus are hidden from casual users).
- Mobile-first UIs — use `<Sheet>` action panels instead.

---

## Anatomy

```
<ContextMenu>
  <ContextMenuTrigger>
    {/* Right-clickable area */}
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem />
    <ContextMenuSeparator />
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubContent>
        <ContextMenuItem />
      </ContextMenuSubContent>
    </ContextMenuSub>
  </ContextMenuContent>
</ContextMenu>
```

---

## Examples

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from 'xertica-ui/ui';

<ContextMenu>
  <ContextMenuTrigger className="flex h-[150px] w-[300px] items-center justify-center rounded-md border border-dashed">
    Right-click here
  </ContextMenuTrigger>
  <ContextMenuContent className="w-48">
    <ContextMenuItem>View</ContextMenuItem>
    <ContextMenuItem>Edit</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem className="text-destructive">Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>;
```

---

## AI Rules

- Destructive items use `className="text-destructive"`.
- Context menus supplement (don't replace) visible action buttons.
- `ContextMenuTrigger` does not require `asChild` — it renders as a `<span>` by default. Apply layout classes directly to the trigger.

---

## Related Components

- [`DropdownMenu`](./dropdown-menu.md) — Click-triggered contextual menu
- [`AlertDialog`](./alert-dialog.md) — For destructive confirmations triggered from menu items