DropdownMenu
Open a compact action menu from a visible trigger.
Anatomy#
Content is portaled; grouped items use the same item subtree as ungrouped items.
Usage#
Use DropdownMenu for a compact set of actions from a visible trigger. Use Select for choosing a form value. Use ContextMenu for actions at a pointer location. Use Popover when the content is not a list of commands. Use Dialog when the user must complete a modal task.
Trigger and items#
DropdownMenu.Trigger adds click, keyboard, and ARIA behavior to the element it renders. It renders
a button; pass as to render another component such as Button, and disabled to prevent
opening. Describe each action in items. An entry that is an array of items forms its own group, and
the menu draws a separator between groups. An item accepts icon, description, kbds, disabled,
and variant: 'danger', and runs onSelect before the menu closes.
Stateful and nested items#
Control a checkbox item with checked and onCheckedChange, or omit checked and set
defaultChecked for uncontrolled state. A radio-group item owns the selected value for its radio
items: pass value and onValueChange (or defaultValue for uncontrolled state) once on the group,
and give each radio item only its value. Selecting a checkbox or radio item keeps the menu open.
Nested children create submenus. Disabled items stay visible but cannot be activated.
A parent item with children can take open and onOpenChange to control its submenu.
onOpenChange reports every open or close request from pointer, keyboard, or click interaction. With
a controlled open, the submenu stays at the prop value until you update it.
Dismissal and positioning#
Escape and outside interaction close the menu by default. Set closeOnEscape={false} or
closeOnOutsideClick={false} to keep it open and receive onClosePrevented for each blocked
attempt. modal hides the rest of the page from assistive technology and prevents the native action
of outside pointer presses while the menu is open. By default the menu also locks body scroll and
renders an overlay behind the content; set preventScroll={false} to keep the page scrollable.
placement (default 'bottom'), align, gutter, shift, flip, and slide tune where the
content opens.
Keyboard interaction#
| Key | Description |
|---|---|
| ↵ / Space / ↓ | Opens the menu from the trigger and focuses the first item. |
| ↑ | Opens the menu from the trigger and focuses the last item. |
| ↓ / ↑ | Moves focus to the next or previous item. |
| ↖ / ↘ | Moves focus to the first or last item. |
| Printable characters | Moves focus to the next item whose text starts with the typed characters. |
| → | Opens the submenu of the focused item. |
| ← | Closes the current submenu and returns to its parent item. |
| ↵ / Space | Activates the focused item, or opens its submenu. |
| Esc | Closes the current menu layer and restores focus. |
| ⇥ | Closes the menu. |
Examples#
Open account actions#
Compose a visible trigger with profile, billing, and shortcut items.
Toggle bookmarks and choose a theme#
Keep checkbox and radio values in application state. Nested children open a theme submenu.
Customize a workspace project view#
Toggle visible fields, include archived projects, and choose a sort order. The list updates from application-owned state; saving a shared view stays disabled for viewers.
Switch layout and show archived#
Checkbox and radio items update a live status line next to the trigger.
Move a file into a folder#
Nested children open a folder submenu. Download stays on the root menu.
Share with a disabled export#
kbds displays shortcut notation. A disabled Export item stays visible but cannot be activated.
Header and footer slots#
Use headerRender and footerRender on DropdownMenu.Content to pin a user identity
banner, search input, or status bar above and below the scrollable menu items.
API Reference#
Attributes#
data-closeddata-disableddata-expandeddata-aligndata-sidedata-dangerdata-highlighteddata-selectedProps#
DropdownMenu#
Trigger#
Renders a <button> element by default.
Content#
Props for the DropdownMenu content component. Renders a <div> element by default.