Dropdown menu

When to use

• For the secondary actions on one item, behind a "More" button: a client row, a program card, an invoice.
• For view options that don't need to be on screen all the time: which columns to show, how to sort.
• For the extra options of a split button (see Button group).

When not to use

• To pick a value for a form field: use a Select. A menu runs actions; a select stores a value.
• For the one main action on a page: show it as a Button, not hidden in a menu.
• For two or three actions with room to show them: use buttons. Hidden actions are found less often.
• For navigation between pages: use links, or the Sidebar.

Anatomy

Open the menu in the example to see parts 2 to 5. Separators split groups of related items.

Variants

Use inset on items without icons in a menu where other items have icons, so the text lines up.

States

The disabled state is in the "Sort" menu above: "Reset to default order" is disabled until you change the order.

Destructive items use text-destructive-text, so they stay above 4.5:1 when highlighted on their 10% destructive tint. Upstream's text-destructive computed to about 4.1:1 there.

Usage guidelines

• Order items by frequency, then group them: view, edit, share; then status changes; then destructive.
• Keep menus short: about 7 items. More than that usually means some belong on the page.
• Don't put a form or free text inside a menu: use a Popover or Dialog.
• In a table, every row's trigger has the same position and icon, and its aria-label includes the row's name.

Content guidelines

• Items start with a verb and name the object when it isn't obvious: "Send message", "Assign program", "Remove client".
• Sentence case, no ending punctuation. Add "…" when the item opens a dialog that asks for more ("Remove client…").
• Checkbox and radio items are nouns, not verbs: "Last check-in", "Next payment".
• Arabic items use the verbal noun consistently: "إرسال رسالة"، "تعيين برنامج"، "إزالة العميل…".

Accessibility

• The trigger has aria-haspopup="menu" and aria-expanded. The panel is a menu; items are menuitem, menuitemcheckbox or menuitemradio.
• A screen reader announces the trigger as "Actions for Sara Al-Harbi, menu button, collapsed", then each item as "Send message, menu item, 2 of 5" (exact words vary by screen reader).
• Focus moves into the menu on open and back to the trigger on close. Nothing outside the menu can be clicked or focused while it is open (it is modal by default).
• Destructive items need a confirmation; color alone doesn't say "this deletes".

RTL

• The menu aligns to the trigger's start or end edge as set by align, so align="end" opens toward the left in RTL.
• Icons and check marks sit at the start of each item and move to the right. Shortcuts sit at the end.
• The submenu chevron mirrors (rtl:-scale-x-100) and submenus open toward the left. Arrow keys follow the direction because the site provides Radix's DirectionProvider.

Tokens used

Read from components/ui/dropdown-menu.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Layerz-(--z-dropdown)
• Opacityopacity-(--opacity-disabled)
• Radiusrounded-md
• Radiusrounded-sm
• Shadowshadow-lg
• Shadowshadow-md
• Typefont-medium
• Typetext-sm
• Typetracking-wide
• Typetext-xs

Props

Replaces in coach-admin

Related

Context menu, Select, Button group, Popover, Alert dialog.