On this page
Menu
Headless, unstyled dropdown menu of actions, with arrow-key navigation, typeahead and nested submenus. Wires role="menu", role="menuitem" and the trigger’s aria-expanded, aria-haspopup and aria-controls.
Use for
- an actions menu opened from a button
- a dropdown of commands, such as edit, duplicate and delete
- a nested submenu inside a menu
- a menu that opens on hover
Practices
| Guidance | Practice |
|---|---|
| Do | Pass label on every Menu.Item. Typeahead matches on it. |
| Do | Nest a Menu.Root inside a Menu.Popup for a submenu. Its trigger becomes a menuitem that opens on hover. |
| Do | Set fallbackPlacements for a menu opened inside another floating surface, so it does not flip onto that surface. |
| Do | Animate with data-starting-style and data-ending-style on Menu.Popup. The popup unmounts once its exit transition ends. |
| Don’t | Pass id to Menu.Positioner. The primitive owns it to pair the trigger’s aria-controls. |
| Don’t | Use it for arbitrary content or a form. Use Popover instead. |
API reference
Menu.Root
Holds the open state, placement and list navigation. Renders no element. Nested inside another menu, it becomes a submenu.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the menu is open, when controlled. |
defaultOpen | boolean | Whether the menu is open on mount, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | Placement | Where the menu sits against its trigger.Default: 'bottom-start', or 'right-start' for a submenu |
sideOffset | SideOffset | Gap to the trigger in px. { x, y } sets one gap per axis.Default: 4, or 0 for a submenu |
fallbackPlacements | Placement[] | Placements to try, in order, when placement does not fit. |
openOnHover | boolean | Opens when a mouse rests on the trigger. A press still opens it and keeps it open.Default: false |
Menu.Trigger
A button that toggles the menu. Carries data-open or data-closed. Inside a parent menu it renders as role="menuitem".
Menu.Portal
Portals its children while the menu is mounted.
| Prop | Type | Description |
|---|---|---|
root | HTMLElement | null | React.RefObject<HTMLElement | null> | The element to portal into.Default: the `Portal` container |
Menu.Positioner
The floating div, placed against the trigger. Carries data-side and the --cl-anchor-*, --cl-available-* and --cl-transform-origin variables. Manages focus and handles Home and End.
Menu.Popup
Wraps the items. Carries data-open, data-closed, data-starting-style and data-ending-style, and is inert while closing.
Menu.Item
A button with role="menuitem". Carries data-active while focused and data-disabled. Clicking it closes the whole menu tree.
| Prop | Type | Description |
|---|---|---|
label | string | The text typeahead matches on. |
disabled | boolean | Sets aria-disabled and skips onClick. The item stays focusable. |
closeOnClick | boolean | Whether a click closes the whole menu tree.Default: true |
Menu.Separator
A div with role="separator" between items.
Menu.Arrow
An optional FloatingArrow svg pointing at the trigger. Carries data-side.
Examples
Actions menu
<Menu.Root>
<Menu.Trigger>Actions</Menu.Trigger>
<Menu.Positioner>
<Menu.Popup>
<Menu.Item label='Edit' onClick={onEdit}>
Edit
</Menu.Item>
<Menu.Separator />
<Menu.Item label='Delete' onClick={onDelete}>
Delete
</Menu.Item>
</Menu.Popup>
</Menu.Positioner>
</Menu.Root>