DropdownMenu

Usage

• Use DropdownMenu to group actions or navigation links in a floating overlay triggered by a button or interactive element.
• Use DropdownMenu for actions and navigation — not for form value selection. Use Select for choosing form values. Use Popover for freeform content like text, forms, or complex UI.
• Limit menus to 7-10 items. Group items with DropdownMenuGroup when the list is longer.
• Limit nesting to one sub-level. Reorganize the menu structure or use labels instead of deeply nested submenus.

Appearance

• Add a leading icon (icon) to items for quick visual identification. Apply icons consistently within each group — never mix icon and non-icon items in the same group.
• Add a description (description) to items to clarify what the action does. Write descriptions as a single, specific sentence — never repeat the label.
• Mark destructive actions with danger styling (isDanger) to warn users the action is irreversible.
• Use DropdownMenuGroup with a label prop to categorize items under labeled sections. Omit label to render an unlabeled divider between groups.
• Use DropdownMenuFooter for supplemental context anchored below all items.
• Use DropdownMenuTrigger for a base inline-text trigger. Use DropdownMenuTriggerButton for a styled Button trigger. Wrap any custom interactive element in DropdownMenuTrigger for non-standard triggers (e.g., an Avatar).

Behaviors

• Items support hover, focus, disabled (isDisabled), and danger (isDanger) states.
• Disable items with isDisabled on DropdownMenuItem. Pair disabled items with a tooltip (tooltip) explaining why the action is unavailable.
• Menu closes on item click, outside click, or Escape. Override per-item with shouldCloseOnClick={false} to keep the menu open — useful for checkbox items or multi-select toggling.
• Use DropdownMenuCheckboxItem for toggle options. Provide isChecked and onCheckedChange. Set shouldCloseOnClick={false} when multiple selections are expected before dismissal.
• Nest submenus with DropdownMenuSub and DropdownMenuSubTrigger. The submenu opens on hover or keyboard activation and displays a trailing chevron.
• Set placement on DropdownMenu to control where the menu opens relative to the trigger. Default is bottom-start. Placement is a preference — the menu auto-adjusts to stay within the viewport.

Content

• Write menu item labels as short, specific verb phrases in sentence case. Start with a verb describing the action (e.g., "Edit details", "Export results").
• Write group labels as concise, single-noun categories in uppercase.
• Write tooltip text on disabled items to explain why the action is unavailable and what would enable it. Never restate the disabled state without explanation.
• Write descriptions to clarify what an action does — never repeat the label or add vague context.

Implementation Notes

• DropdownMenu is a compound component. Compose DropdownMenu with DropdownMenuTrigger or DropdownMenuTriggerButton, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuFooter, DropdownMenuSub, and DropdownMenuSubTrigger as children.
• DropdownMenuItem renders as a non-interactive div by default. Provide onClick or href to make it interactive (renders as a button or link). Items without onClick or href are static content.
• DropdownMenuCheckboxItem requires isChecked (boolean) and onCheckedChange (callback). It does not accept the icon prop — the check indicator is managed internally.
• DropdownMenuTriggerButton extends Button — pass any Button prop (e.g., variant, icon, iconPosition, isIconOnly, aria-label).
• DropdownMenuSubTrigger automatically renders a trailing chevron icon. Pass children as the label text and an optional icon prop.
• In Ember, components use the Pluma prefix: <PlumaDropdownMenu>, <PlumaDropdownMenuTriggerButton>, <PlumaDropdownMenuItem>, etc. Content is passed via {{yield}} block slots.
• DropdownMenu accepts a placement prop (from Floating UI's Placement type). Default is bottom-start.
• shouldRestrictSize defaults to false on DropdownMenu (unlike the base PopoverPrimitive where it defaults to true), so the menu is not viewport-constrained by default.