Skip to content
Mosaic
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

GuidancePractice
DoPass label on every Menu.Item. Typeahead matches on it.
DoNest a Menu.Root inside a Menu.Popup for a submenu. Its trigger becomes a menuitem that opens on hover.
DoSet fallbackPlacements for a menu opened inside another floating surface, so it does not flip onto that surface.
DoAnimate with data-starting-style and data-ending-style on Menu.Popup. The popup unmounts once its exit transition ends.
Don’tPass id to Menu.Positioner. The primitive owns it to pair the trigger’s aria-controls.
Don’tUse 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.

PropTypeDescription
openbooleanWhether the menu is open, when controlled.
defaultOpenbooleanWhether the menu is open on mount, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placementPlacementWhere the menu sits against its trigger.Default: 'bottom-start', or 'right-start' for a submenu
sideOffsetSideOffsetGap to the trigger in px. { x, y } sets one gap per axis.Default: 4, or 0 for a submenu
fallbackPlacementsPlacement[]Placements to try, in order, when placement does not fit.
openOnHoverbooleanOpens 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.

PropTypeDescription
rootHTMLElement | 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.

PropTypeDescription
labelstringThe text typeahead matches on.
disabledbooleanSets aria-disabled and skips onClick. The item stays focusable.
closeOnClickbooleanWhether 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

TSX
<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>