Skip to content
Mosaic
On this page

Menu

A dropdown of actions opened from a trigger. Handles focus, arrow keys and typeahead, and closes when an item is clicked.

Use for

  • a list of actions behind an ellipsis button
  • a row or card overflow menu
  • a destructive action among others, with color="negative"

Practices

GuidancePractice
DoGive every Menu.Item a label for typeahead. It is not rendered or announced, so the item also needs visible text in Menu.Label.
DoPut the item text in Menu.Label, not straight in Menu.Item, so it lines up and truncates.
DoUse the same Menu.Media size for every item in one menu, so the text starts on one line.
DoPass an aria-label to a Menu.Trigger with no children. The default ellipsis has no name.
Don’tUse it to pick a value. Use Select instead.

API reference

Menu.Root

Holds the open state and placement. Renders no element.

PropTypeDescription
openbooleanWhether the menu is open, when controlled.
defaultOpenbooleanWhether the menu starts open, when uncontrolled.Default: false
onOpenChange(open: boolean) => voidCalled with the new open state.
placementPlacementSide and alignment against the trigger.Default: 'bottom-start', or 'right-start' for a submenu
sideOffsetSideOffsetGap from the trigger in px, or { x, y } per axis.Default: 4, or 0 for a submenu
fallbackPlacementsPlacement[]Where the menu goes, in order, when placement does not fit.Default: the opposite side
openOnHoverbooleanAlso opens while the mouse rests on the trigger.Default: false

Menu.Trigger

Opens the menu. Renders a small neutral ghost Button with an ellipsis, or children as its label, or the render element.

Slot: cl-menu-trigger

PropTypeDescription
focusableWhenDisabledbooleanKeeps the default trigger in the tab order while disabled. A render trigger handles this itself.Default: false

Menu.Popup

The floating, scrollable surface. Portals and positions itself.

Slot: cl-menu-popup

PropTypeDescription
portalRootMenuPortalProps['root']The container the menu portals into.Default: `document.body`

Menu.Item

One action, as a button. What it shows is the Menu.Media, Menu.Label and Menu.Indicator inside it.

Slot: cl-menu-item

PropTypeDescription
labelstringThe text typeahead matches on. Not rendered and not the accessible name.
color'neutral' | 'negative'neutral or negative.Default: 'neutral'
disabledbooleanDisables the item and ignores its onClick.
closeOnClickbooleanCloses the menu after a click.Default: true

Menu.Media

A square leading column that centers an icon, image or avatar.

Slot: cl-menu-item-media

PropTypeDescription
sizeMenuMediaSizesm fits an icon or avatar, xs a bare glyph. Sets the row height.Default: 'sm'

Menu.Label

The item text. Fills the space between media and indicator and cuts to one line.

Slot: cl-menu-item-label

Menu.Indicator

A small square trailing slot, such as for a spinner while the action runs.

Slot: cl-menu-item-indicator

Menu.Separator

A full-width divider between groups of items.

Slot: cl-menu-separator

Examples

An overflow menu

TSX
<Menu.Root>
  <Menu.Trigger aria-label='More actions' />
  <Menu.Popup>
    <Menu.Item label='Rename' onClick={onRename}>
      <Menu.Label>Rename</Menu.Label>
    </Menu.Item>
    <Menu.Separator />
    <Menu.Item label='Delete' color='negative' onClick={onDelete}>
      <Menu.Label>Delete</Menu.Label>
    </Menu.Item>
  </Menu.Popup>
</Menu.Root>