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
| Guidance | Practice |
|---|---|
| Do | Give every Menu.Item a label for typeahead. It is not rendered or announced, so the item also needs visible text in Menu.Label. |
| Do | Put the item text in Menu.Label, not straight in Menu.Item, so it lines up and truncates. |
| Do | Use the same Menu.Media size for every item in one menu, so the text starts on one line. |
| Do | Pass an aria-label to a Menu.Trigger with no children. The default ellipsis has no name. |
| Don’t | Use it to pick a value. Use Select instead. |
API reference
Menu.Root
Holds the open state and placement. Renders no element.
| Prop | Type | Description |
|---|---|---|
open | boolean | Whether the menu is open, when controlled. |
defaultOpen | boolean | Whether the menu starts open, when uncontrolled.Default: false |
onOpenChange | (open: boolean) => void | Called with the new open state. |
placement | Placement | Side and alignment against the trigger.Default: 'bottom-start', or 'right-start' for a submenu |
sideOffset | SideOffset | Gap from the trigger in px, or { x, y } per axis.Default: 4, or 0 for a submenu |
fallbackPlacements | Placement[] | Where the menu goes, in order, when placement does not fit.Default: the opposite side |
openOnHover | boolean | Also 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
| Prop | Type | Description |
|---|---|---|
focusableWhenDisabled | boolean | Keeps 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
| Prop | Type | Description |
|---|---|---|
portalRoot | MenuPortalProps['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
| Prop | Type | Description |
|---|---|---|
label | string | The text typeahead matches on. Not rendered and not the accessible name. |
color | 'neutral' | 'negative' | neutral or negative.Default: 'neutral' |
disabled | boolean | Disables the item and ignores its onClick. |
closeOnClick | boolean | Closes 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
| Prop | Type | Description |
|---|---|---|
size | MenuMediaSize | sm 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
<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>